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/

快速升级步骤

第一步 替换依赖



     io.springfox
     springfox-swagger2
     ${swagger.version}




	org.springdoc
	springdoc-openapi-webmvc-core
    ${xxx.version}

第二步 替换相关注解

用 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

swagger快速升级方案_第1张图片

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

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

swagger快速升级方案_第2张图片

 常用替换表达式:

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

swagger快速升级方案_第3张图片

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

扩展

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

swagger快速升级方案_第4张图片

 在pom.xml文件那里会看到Dependency Analyzer,在这个界面可以查找相关依赖包swagger快速升级方案_第5张图片

 

你可能感兴趣的:(Java,swagger升级,springboot)