swagger

2020.8.16更新：在项目使用时发现，目前3.0对file上传的支持存在问题

最近在写项目时，作为一直求新的少年，一直会关注下依赖包的最新版，在导入SpringFox-swagger 2.9.10发现一直无法通过/swagger-ui.html访问，百度又是清一色的兼容swagger 2.9.2之前的版本教程，Google了之后发现，2.9.10引入了WebFlux，注解也变了，这之前的项目迁移起来就多了点成本，而进一步了解到，七月份SpringFox发布了 3.0.0 版本，同时发布了springfox-boot-starter。

在之前的项目中，如果要使用swagger，需要引入以下的两个依赖：

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>3.0.0</version>
    <scope>compile</scope>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>3.0.0</version>
    <scope>compile</scope>
</dependency>

大致看了一下，这个版本的亮点有如下一些：

• Spring 5，Webflux 支持（仅请求映射支持，尚不支持功能端点）
• Spring Integration 支持
• Spring Boot 支持 springfox-boot-starter 依赖性（零配置，自动配置支持）
• 具有自动完成功能的文档化配置属性
• 更好的规范兼容性
• 支持 OpenApi 3.0.3
• 几乎零依赖性（唯一需要的库是 spring-plugin、pswagger-core）
• 现有的 swagger2 注释将继续有效，并丰富 open API 3.0 规范

对于这次的更新，我觉得比较突出的几点：Webflux的支持；对OpenApi 3的支持；以及对Swagger 2的兼容（可以几乎没成本的做升级了）。

上手起来如下：

1. 建工程

2. 导入依赖

   <dependency>
       <groupId>io.springfox</groupId>
       <artifactId>springfox-boot-starter</artifactId>
       <version>3.0.0</version>
   <dependency>
   

   相比之前，简洁了不少！

3. 应用主类增加注解@EnableOpenApi。

4. 使用注解配置一些接口文档

值得注意的是，这次更新，移除了原来默认的swagger页面路径：http://host/context-path/swagger-ui.html，新增了两个可访问路径：http://host/context-path/swagger-ui/index.html和http://host/context-path/swagger-ui/

同时也了解下OpenApi上的注解对应关系

@ApiParam -> @Parameter
@ApiOperation -> @Operation
@Api -> @Tag
@ApiImplicitParams -> @Parameters
@ApiImplicitParam -> @Parameter
@ApiIgnore -> @Parameter(hidden = true) or @Operation(hidden = true) or @Hidden
@ApiModel -> @Schema
@ApiModelProperty -> @Schema