swagger快速升级方案

背景

在使用SpringBoot 2.6以前去创建API文档工具一般会采用SpringFox提供的Swagger库，但是由于SpringBoot版本的不断升级和SpringFox摆烂不更新，导致了SpringBoot2.6之后的项目无法使用SpringFox去生成API文档，或者可以使用但是有很多的bug。

SpringDoc是一款可以结合SpringBoot使用API文档生成工具，基于OpenAPI 3，而且项目维护和社区都在不断更新，不仅支持SpringMVC，而且还支持Spring WebFlux项目。

SpringDoc是SpringBoot 的API文档工具。官网：https://springdoc.org/

快速升级步骤

第一步 替换依赖

<!-- 原依赖包 -->
<dependency>
     <groupId>io.springfox</groupId>
     <artifactId>springfox-swagger2</artifactId>
     <version>${swagger.version}</version>
</dependency>

<!-- 新的依赖包 -->
<dependency>
	<groupId>org.springdoc</groupId>
	<artifactId>springdoc-openapi-webmvc-core</artifactId>
    <version>${xxx.version}</version>
</dependency>

第二步 替换相关注解

用 swagger 3 注释替换 swagger 2 注释（它已经包含在springdoc-openapi-ui依赖项中）。swagger 3 注释的包是io.swagger.v3.oas.annotations.

• @Api→@Tag
• @ApiIgnore→@Parameter(hidden = true)或@Operation(hidden = true)或@Hidden
• @ApiImplicitParam→@Parameter
• @ApiImplicitParams→@Parameters
• @ApiModel→@Schema
• @ApiModelProperty(hidden = true)→@Schema(accessMode = READ_ONLY)
• @ApiModelProperty→@Schema
• @ApiOperation(value = "foo", notes = "bar")→@Operation(summary = "foo", description = "bar")
• @ApiParam→@Parameter
• @ApiResponse(code = 404, message = "foo")→@ApiResponse(responseCode = "404", description = "foo")

这里如果代码很多，一个个进行替换会很耗时和麻烦，可以用idea的全文（正则）替换。

例如：

import io.swagger.annotations.Api;
import io.swagger.v3.oas.annotations.tags.Tag;

@Api\(value = (.*), tags = (.*)\)
@Tag\(name= $2, description = $1\)

 打开idea全局替换窗口，查找路径：idea->Edit->Find->Replace in Files...

快捷键：Ctrl+Shift+R

 输入如下正则表达式，这里需要根据自己实际写的代码使用表达式，像下面这样，就可以把

@Api(value = "ActivityAppController", tags = "招商活动管理")
->@Tag(name= "招商活动管理", description = "ActivityAppController")

 常用替换表达式：

import io.swagger.annotations.Api;
->
import io.swagger.v3.oas.annotations.tags.Tag;

查找方式示例：
@Api\(value = (.*), tags = (.*)\)
@Tag\(name= $2, description = $1\)


import io.swagger.annotations.ApiOperation;
->
import io.swagger.v3.oas.annotations.Operation;

查找方式示例：
@ApiOperation\(value = (.*), notes = (.*)\)
@Operation\(summary = $1, description = $2\)

查找方式示例：
@ApiOperation\((.*)\)
@Operation\(summary = $1\)


import io.swagger.annotations.ApiResponses;
->
import io.swagger.v3.oas.annotations.responses.ApiResponses;

import io.swagger.annotations.ApiResponse;
->
import io.swagger.v3.oas.annotations.responses.ApiResponse;

查找方式示例：
@ApiResponse\(code = HttpStatus.SC_OK, message = (.*)\)
@ApiResponse(responseCode = "200", description = $1)


import io.swagger.annotations.ApiParam;
->
import io.swagger.v3.oas.annotations.Parameter;

查找方式示例：
#unicode中文范围 \u4e00-\u9eff
@ApiParam\(value = ("[\w|\u4e00-\u9eff]+")
@Parameter\(description = $1


import io.swagger.annotations.ApiModelProperty;
->
import io.swagger.v3.oas.annotations.media.Schema;

查找方式示例：
@ApiModelProperty\((.*)\)
@Schema\(description = $1\)

非正则:
import io.swagger.annotations.*;
->
import io.swagger.v3.oas.annotations.*;
import io.swagger.v3.oas.annotations.responses.*;
import io.swagger.v3.oas.annotations.tags.*;

第三步 导包

上面替换完如果还有一些包没有导入，或者还有一些旧的无用包还在代码里面，则可以使用idea的自动导包，快速处理。选择某个目录，右键->Optimize Imports，或者使用快捷键：Ctrl+Alt+O

 至此升级完成，build项目看是否有报错。

扩展

查看maven依赖技巧：可以使用Maven Helper插件来查看相关依赖，以确保移除了swagger2相关依赖。

 在pom.xml文件那里会看到Dependency Analyzer，在这个界面可以查找相关依赖包