Swagger文档管理
swagger是一个流行的API开发框架，这个框架以“开放API声明”（OpenAPI Specification，OAS）为基础，对整个API的开发周期都提供了相应的解决方案，是一个非常庞大的项目（包括设计、编码和测试，几乎支持所有语言）。
OpenAPI规范
OpenAPI规范（OAS）为HTTP API定义了一个与语言无关的标准接口，使得人和计算机都可以在不使用源代码、文档或监听网络通信的情况下，具备发现和理解服务的能力。正确定义后，使用者可以使用最少的实现逻辑来理解远程服务并与之交互。
文档生成工具可以使用OpenAPI定义来显示API，代码生成工具可以生成各种编程语言的服务器和客户端代码，测试工具以及许多其他工具也可以使用OpenAPI定义。
Swagger简介
OAS本身是一个API规范，它用于描述一整套API接口，包括一个接口是GET还是POST请求啊，有哪些参数哪些header啊，都会被包括在这个文件中。它在设计的时候通常是YAML格式，这种格式书写起来比较方便，而在网络中传输时又会以json形式居多，因为json的通用性比较强。
由于Spring的流行，Marty Pitt编写了一个基于Spring的组件swagger- springmvc，用于将swagger集成到springmvc中来。而springfox则是从这个组件发展而来，同时springfox也是一个新的项目，本文仍然是使用其中的一个组件springfox- swagger2。
pringfox- swagger2依然是依赖OSA规范文档，也就是一个描述API的json文件，而这个组件的功能就是帮助我们自动生成这个json文件，我们会用到的另外一个组件springfox- swagger-ui就是将这个json文件解析出来，用一种更友好的方式呈现出来。
Swagger 是一个用于生成、描述和调用 RESTful 接口的 Web 服务。通俗的来讲，Swagger 就是将项目中所有（想要暴露的）接口展现在页面上，并且可以进行接口调用和测试的服务。
从上述 Swagger 定义我们不难看出 Swagger 有以下 3 个重要的作用：
- 将项目中所有的接口展现在页面上，这样后端程序员就不需要专门为前端使用者编写专门的接口文档；
- 当接口更新之后，只需要修改代码中的 Swagger 描述就可以实时生成新的接口文档了，从而规避了接口文档老旧不能使用的问题；
- 通过 Swagger 页面，我们可以直接进行接口调用，降低了项目开发阶段的调试成本。
Swagger3完全遵循了 OpenAPI 规范。
Swagger和SpringFox有啥关系？
Swagger 可以看作是一个遵循了 OpenAPI 规范的一项技术，而 springfox 则是这项技术的具体实现。 就好比 Spring 中的 IOC 和 DI 的关系 一样，前者是思想，而后者是实现。
什么是Knife4J? 和Swagger什么关系？
本质是Swagger的增强解决方案，前身只是一个SwaggerUI（swagger-bootstrap-ui）
Knife4j是为Java MVC框架集成Swagger生成Api文档的增强解决方案, 前身是swagger-bootstrap-ui,取名kni4j是希望她能像一把匕首一样小巧,轻量,并且功能强悍!
Knife4j的前身是swagger-bootstrap-ui，为了契合微服务的架构发展,由于原来swagger-bootstrap-ui采用的是后端Java代码+前端Ui混合打包的方式,在微服务架构下显的很臃肿,因此项目正式更名为knife4j
更名后主要专注的方面
- 前后端Java代码以及前端Ui模块进行分离,在微服务架构下使用更加灵活
- 提供专注于Swagger的增强解决方案,不同于只是改善增强前端Ui部分
项目实战
Maven项目依赖
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
</dependency>
Swagger注解
Swagger通过注解的方式对接口进行描述，以下是一些常用生成接口文档的注解。
@Api
@Api用在类上，说明该类的作用。可以标记一个Controller类作为Swagger文档资源 tags：接口说明，可以在页面中显示。可以配置多个，当配置多个的时候，在页面中会显示多个接口的信息。
@Api(tags={"用户接口"})
@RestController
public class UserController {
}
@ApiModel
@ApiModel用在类上，表示对类进行说明，用于实体类中的参数接收说明。
@ApiModel(value = "com.param.AddUserParam", description = "新增用户参数")
public class AddUserParam {
}
@ApiModelProperty
@ApiModelProperty()用于字段，表示对model属性的说明。
@Data
@ApiModel(value = "com.param.AddUserParam", description = "新增用户参数")
public class AddUserParam {
@ApiModelProperty(value="ID")
private String id;
@ApiModelProperty(value="名称")
private String name;
@ApiModelProperty(value="年龄")
private int age;
}
ApiParam
@ApiParam用于Controller中方法的参数说明。
- value：参数说明
- required：是否必填
@PostMapping("/user") public UserDto addUser(@ApiParam(value = " 新增用户参数 ", required = true) @RequestBody AddUserParam param) { System.err.println(param.getName()); return new UserDto(); }
ApiOperation
@ApiOperation用在Controller里的方法上，说明方法的作用，每一个接口的定义。
- value：接口名称
- notes：详细说明 ```java @ApiOperation(value = “新增用户”, notes=”详细描述”)
public UserDto addUser(@ApiParam(value = “ 新增用户参数 “, required = true) @RequestBody AddUserParam param) {
}
### ApiResponse和ApiResponses
@ApiResponse用于方法上，说明接口响应的一些信息；
@ApiResponses组装了多个@ApiResponse。
```java
@ApiResponses({ @ApiResponse(code = 200, message = "OK", response = UserDto.class) })
@PostMapping("/user")
public UserDto addUser(@ApiParam(value = " 新增用户参数 ", required = true) @RequestBody AddUserParam param) {
}
ApiImplicitParam和ApiImplicitParams
用于方法上，为单独的请求参数进行说明。
- name：参数名，对应方法中单独的参数名称。
- value：参数中文说明。
- required：是否必填。
- paramType：参数类型，取值为path、query、body、header、form。
- dataType：参数数据类型。
- defaultValue：默认值。
@ApiImplicitParams({ @ApiImplicitParam(name="id",value="用户ID",dataType="string", paramType = "query", required=true, defaultValue="1") }) @ApiResponses({ @ApiResponse(code = 200, message = "OK", response = UserDto.class) }) @GetMapping("/user") public UserDto getUser(@RequestParam("id")String id) { return new UserDto(); }
