参考地址
说明
以下配置是基于 spring-boot 项目.
注解
- @API() 用于类;
表示标识这个类是 swagger 的资源
- @ApiOperation() 用于方法;
表示一个 http 请求的操作
- @ApiParam() 用于方法, 参数, 字段说明;
表示对参数的添加元数据 (说明或是否必填等)
- @ApiModel() 用于类
表示对类进行说明, 用于参数用实体类接收
- @ApiModelProperty() 用于方法, 字段
表示对 model 属性的说明或者数据操作更改
- @ApiIgnore() 用于类, 方法, 方法参数
表示这个方法或者类被忽略
- @ApiImplicitParam() 用于方法
表示单独的请求参数
- @ApiImplicitParams() 用于方法
包含多个 @ApiImplicitParam
实践
@API() - 用于类; 表示标识这个类是 swagger 的资源
tags - 表示说明
value - 也是说明, 可以使用 tags 替代
但是 tags 如果有多个值, 会生成多个 list
- @API(value="用户 controller",tags={
- "用户操作接口"
- })
- @RestController
- public class UserController {
- }
@ApiOperation() - 用于方法; 表示一个 http 请求的操作
value 用于方法描述
notes 用于提示内容
tags 可以重新分组 (视情况而用)
@ApiParam() - 用于方法, 参数, 字段说明; 表示对参数的添加元数据 (说明或是否必填等)
name - 参数名
value - 参数说明
required - 是否必填
- @API(value="UserController",tags={"用户接口"})
- @RestController
- public class UserController {
- @ApiOperation(value="获取用户信息",tags={"获取用户信息"},notes="注意")
- @GetMapping("/getUserInfo")
- public User getUserInfo(@ApiParam(name="id",value="用户 id",required=true) Long id,@ApiParam(name="username",value="用户名") String username) {
- User user = userService.getUserInfo();
- return user;
- }
- }
@ApiModel() - 用于类 ; 表示对类进行说明, 用于参数用实体类接收
value - 表示对象名
description - 描述
@ApiModelProperty() - 用于方法, 字段; 表示对 model 属性的说明或者数据操作更改
value - 字段说明
name - 重写属性名字
dataType - 重写属性类型
required - 是否必填
example - 举例说明
hidden - 隐藏
- @ApiModel(value="user",description="用户对象")
- @Data
- public class User implements Serializable{
- private static final long serialVersionUID = 1L;
- @ApiModelProperty(value="用户名",name="username",example="xingguo")
- private String username;
- @ApiModelProperty(value="状态",name="state",required=true)
- private Integer state;
- private String password;
- private String nickName;
- private Integer isDeleted;
- @ApiModelProperty(value="ids",hidden=true)
- private String[] ids;
- private List<String> idList;
- }
- @ApiOperation("修改用户信息")
- @PostMapping("/updateUserInfo")
- public int updateUserInfo(@RequestBody @ApiParam(name="用户对象",value="json 格式",required=true) User user){
- int num = userService.updateUserInfo(user);
- return num;
- }
@ApiIgnore() - 用于类或者方法上, 可以不被 swagger 显示在页面上.
@ApiImplicitParam() - 用于方法, 表示单独的请求参数
@ApiImplicitParams() - 用于方法, 包含多个 @ApiImplicitParam
name - 参数 ming
value - 参数说明
dataType - 数据类型
paramType - 参数类型
example - 举例说明
- @ApiOperation("查询测试")
- @GetMapping("select")
- //@ApiImplicitParam(name="name",value="用户名",dataType="String", paramType = "query")
- @ApiImplicitParams({
- @ApiImplicitParam(name="name",value="用户名",dataType="string", paramType = "query",example="xingguo"),
- @ApiImplicitParam(name="id",value="用户 id",dataType="long", paramType = "query")
- })
- public void select(){
- }
pom 依赖
- <dependency>
- <groupId>io.springfox</groupId>
- <artifactId>springfox-swagger2</artifactId>
- <version>2.9.2</version>
- </dependency>
- <dependency>
- <groupId>io.springfox</groupId>
- <artifactId>springfox-swagger-ui</artifactId>
- <version>2.9.2</version>
- </dependency>
- <!-- 下面这个界面更好看, 更好用 -->
- <dependency>
- <groupId>com.GitHub.xiaoymin</groupId>
- <artifactId>swagger-Bootstrap-ui</artifactId>
- <version>1.9.5</version>
- </dependency>
具体配置
- (包含分组)
- import com.google.common.base.Predicates;
- import org.springframework.context.annotation.Bean;
- import org.springframework.context.annotation.Configuration;
- import springfox.documentation.builders.ApiInfoBuilder;
- import springfox.documentation.builders.ParameterBuilder;
- import springfox.documentation.builders.PathSelectors;
- import springfox.documentation.builders.RequestHandlerSelectors;
- import springfox.documentation.schema.ModelRef;
- import springfox.documentation.service.ApiInfo;
- import springfox.documentation.service.Contact;
- import springfox.documentation.service.Parameter;
- import springfox.documentation.spi.DocumentationType;
- import springfox.documentation.spring.web.plugins.Docket;
- import springfox.documentation.swagger2.annotations.EnableSwagger2;
- import java.util.ArrayList;
- import java.util.List;
- /**
- * swagger-API 配置
- *
- * @author wzm
- * @version 1.0.0
- * @date 2019/6/15
- **/
- @Configuration
- @EnableSwagger2
- @EnableSwaggerBootstrapUI
- public class Swagger2 {
- /**
- * http://localhost:8085/fabric.NET/swagger-ui.html
- * http://localhost:8085/fabric.NET/doc.HTML
- */
- private static final String SWAGGER_SCAN_BUSINESS_PACKAGE = "com.thyc.fabric.controller.business";
- private static final String BUSINESS_VERSION = "1.0.0";
- private static final String SWAGGER_SCAN_FABRIC_PACKAGE = "com.thyc.fabric.controller.fabric";
- private static final String FABRIC_VERSION = "1.0.0";
- @Bean
- public Docket createBusinessApi() {
- List<Parameter> pars = new ArrayList<>();
- ParameterBuilder ticketPar1 = new ParameterBuilder();
- ticketPar1.name("Authorization").description("登录令牌")
- .modelRef(new ModelRef("string")).parameterType("header")
- .required(false).build();
- pars.add(ticketPar1.build());
- return new Docket(DocumentationType.SWAGGER_2)
- .globalOperationParameters(pars)
- // 分组名不支持中文
- .groupName("business")
- .apiInfo(apiBusinessInfo())
- .pathMapping("/")
- .select()
- // 对所有 API 进行监控
- .apis(RequestHandlerSelectors.basePackage(SWAGGER_SCAN_BUSINESS_PACKAGE))
- // 错误路径不监控
- .paths(Predicates.not(PathSelectors.regex("/error.*")))
- // 对根下所有路径进行监控
- .paths(PathSelectors.regex("/.*"))
- .build();
- }
- private ApiInfo apiBusinessInfo() {
- Contact contact = new Contact("thyc","thyc.com","[email protected]");
- return new ApiInfoBuilder()
- // 设置文档的标题
- .title("Business")
- // 设置文档的描述 ->1.Overview
- .description("业务模块数据管理")
- // 设置文档的版本信息 -> 1.1 Version information
- .termsOfServiceUrl("http://localhost:8085/fabric-net")
- .contact(contact)
- .version(BUSINESS_VERSION)
- .build();
- }
- //------------------------------------------------------------------------------------------------------------------
- @Bean
- public Docket createFabricApi() {
- List<Parameter> pars = new ArrayList<Parameter>();
- ParameterBuilder ticketPar1 = new ParameterBuilder();
- ticketPar1.name("Authorization").description("登录令牌")
- .modelRef(new ModelRef("string")).parameterType("header")
- .required(false).build();
- pars.add(ticketPar1.build());
- return new Docket(DocumentationType.SWAGGER_2)
- .globalOperationParameters(pars)
- // 分组名不支持中文
- .groupName("fabric")
- .apiInfo(apiFabricInfo())
- .pathMapping("/")
- .select()
- // 对所有 API 进行监控
- .apis(RequestHandlerSelectors.basePackage(SWAGGER_SCAN_FABRIC_PACKAGE))
- // 错误路径不监控
- .paths(Predicates.not(PathSelectors.regex("/error.*")))
- // 对根下所有路径进行监控
- .paths(PathSelectors.regex("/.*"))
- .build();
- }
- private ApiInfo apiFabricInfo() {
- Contact contact = new Contact("thyc","thyc.com","[email protected]");
- return new ApiInfoBuilder()
- // 设置文档的标题
- .title("Fabric-Network")
- // 设置文档的描述 ->1.Overview
- .description("超级账本网络信息管理")
- // 设置文档的版本信息 -> 1.1 Version information
- .termsOfServiceUrl("http://localhost:8085/fabric-net")
- .contact(contact)
- .version(FABRIC_VERSION)
- .build();
- }
- }
来源: http://www.bubuko.com/infodetail-3394544.html