Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。
swagger 官方Demo供参考
swagger注解
swagger通过注解表明该接口会生成文档，包括接口名、请求方法、参数、返回信息的等等。
API详细说明
@Api(tags = "收付费方式变更") 常用
@ApiOperation("获取用户列表") 常用
@ApiParam(value = "用户Id") 常用
@ApiImplicitParam：
作用在方法上，表示单独的请求参数, 一个非常强大且重要的注解, 作用和ApiParam类似
开始使用
pom中导入dependency
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.8.0</version> </dependency> <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.8.0</version> </dependency>
- Application 中启用 @EnableSwagger2
- config的配置类
package com.abc.xxx; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import springfox.documentation.builders.ApiInfoBuilder; import springfox.documentation.builders.PathSelectors; import springfox.documentation.builders.RequestHandlerSelectors; import springfox.documentation.service.ApiInfo; import springfox.documentation.spi.DocumentationType; import springfox.documentation.spring.web.plugins.Docket; /** * @author zh * @ClassName cn.saytime.Swgger2 * @Description * @date 2017-07-10 22:12:31 */ @Configuration public class Swagger2 { private static final String SWAGGER_SCAN_BASE_PACKAGE = "com.baomidou.ant.abc"; private static final String VERSION = "0.0.1"; @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select() // 选择那些路径和api会生成document .apis(RequestHandlerSelectors.basePackage(SWAGGER_SCAN_BASE_PACKAGE)) .paths(PathSelectors.any())// 对根下所有路径进行监控 .build(); } private static ApiInfo apiInfo() { return new ApiInfoBuilder() .version(VERSION) .build(); } }
/** * <p> * 收付费方式变更总表 前端控制器 * </p> * * @author someone * @since 2019-07-15 */ @Api(tags = "收付费方式变更") @RestController @RequestMapping("/test") public class PaychangeTotalController { /** * 查询用户列表 * * @return */ @ApiOperation("获取用户列表") @GetMapping("/users/{id}") public String getUserList(@ApiParam(value = "用户", required = true) @PathVariable String id) { return "Npp"; } @ApiOperation("小猫变小狗") @PostMapping( value = "/edit") public Result<?> edit (@RequestBody Cat cat){ Dog dog = new Dog(); dog.setNickName("小白"); return JSONResult.ok(dog); } }
总结常用swagger-ui注解
@Api() 用于类
该注解将一个Controller（Class）标注为一个swagger资源（API）。在默认情况下，Swagger-Core只会扫描解析具有@Api注解的类，而会自动忽略其他类别资源（JAX-RS endpoints，Servlets等等）的注解。该注解包含以下几个重要属性：
- tags：API分组标签。具有相同标签的API将会被归并在一组内展示。
- value：如果tags没有定义，value将作为Api的tags使用
- description：对该API的详细描述信息
- position：如果一个controller中有多个请求方法，可以通过该属性来指定API在swagger-ui中的显示顺序
@ApiOperation() 用于方法
在指定的（路由）路径上，对一个操作或HTTP方法进行描述。具有相同路径的不同操作会被归组为同一个操作对象。不同的HTTP请求方法及路径组合构成一个唯一操作。此注解的属性有：
- value：对操作的简单说明，长度为120个字母，60个汉字。
- notes：对操作的详细说明。
- httpMethod：HTTP请求的动作名，可选值有："GET", "HEAD", "POST", "PUT", "DELETE", "OPTIONS" and "PATCH"。
code：默认为200，有效值必须符合标准的HTTP Status Code Definitions。
@ApiParam() 用于方法，参数，字段说明
增加对参数的元信息说明，主要的属性有：
required：指定该参数是否为必传参数
value：对该参数含义的简短说明
@ApiResponses（）用于包装类
注解@ApiResponse的包装类，数组结构。
即使需要使用一个@ApiResponse注解，也需要将@ApiResponse注解包含在注解@ApiResponses内。
@ApiResponse（）用于方法的返回结果
描述一个操作可能的返回结果。
当REST API请求发生时，这个注解可用于描述所有可能的成功与错误码。
可以用，也可以不用这个注解去描述操作的返回类型，但成功操作的返回类型必须在@ApiOperation中定义。
如果API具有不同的返回类型，那么需要分别定义返回值，并将返回类型进行关联。
但Swagger不支持同一返回码，多种返回类型的注解。注意：这个注解必须被包含在@ApiResponses注解中。
字段说明：
code：HTTP请求返回码。有效值必须符合标准的HTTP Status Code Definitions。
message：用于对返回信息作详细说明，对请求结果的描述信息
response：返回类型信息，必须使用完全限定类名，比如
“com.xyz.cc.Person.class”。
responseContainer：如果返回类型为容器类型，可以设置相应的值。有效值为 "List",
"Set" or "Map"，其他任何无效的值都会被忽略
2）Model的注解
@ApiModel() 用于类
提供对Swagger model额外信息的描述。在标注@ApiOperation注解的操作内，所有的类将自动被内省（introspected），但利用这个注解可以做一些更加详细的model结构说明。主要属性有：
value：model的别名，默认为类名
description：对model的详细描述
** @ApiModelProperty() 用于model类的属性**
表示对model属性的说明或者数据操作更改，主要的属性有：
value：描述
required：标识该属性是否为必须值
example：给出该属性的示例值
allowableValues : 可选值, 像这样@ApiModelProperty(allowableValues = "range[1,5]") 或者 @ApiModelProperty(allowableValues = "111, 222")
3）其他注解
@ApiIgnore() 用于类，方法，方法参数
表示这个方法或者类被忽略
- @ApiImplicitParam() 用于方法
表示单独的请求参数
- @ApiImplicitParams() 用于方法
该注解可以包含多个 @ApiImplicitParam
swagger2 如何匹配多个controller
@Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select() .apis(RequestHandlerSelectors.basePackage("com.shubing")) .paths(PathSelectors.any()) .build(); }
或者
@Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select() .apis(RequestHandlerSelectors.withClassAnnotation(RestController.class)) .paths(PathSelectors.any()) .build(); }
使用以下两种，都是错误的
@Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select() .apis(RequestHandlerSelectors.basePackage("com.shubing.*.controller")) .paths(PathSelectors.any()) .build(); } @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select() .apis(RequestHandlerSelectors.basePackage("com.shubing.course.controller")) .apis(RequestHandlerSelectors.basePackage("com.shubing.user.controller")) .paths(PathSelectors.any()) .build(); }
不同环境中配置是否启用swagger
@Value("${swagger.enable}") private boolean enableSwagger; @Bean public Docket customImplementation(){ return new Docket(SWAGGER_2) .apiInfo(apiInfo()) .enable(enableSwagger) //<--- Flag to enable or disable possibly loaded using a property file .includePatterns(".*pet.*"); }
然后，需要在dev和test环境中配置：
swagger: enable: true
