背景

在使用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.*;