SpringBoot 3.0 升级之 Swagger 升级

文章目录

- SpringFox3.0.0
- openapi3
- [Swagger 注解迁移](#Swagger 注解迁移)

最近想尝试一下最新的 SpringBoot 项目，于是将自己的开源项目进行了一些升级。

JDK 版本从 JDK8 升级至 JDK17。
SpringBoot 版本从 SpringBoot 2.7.3 升级到 SpringBoot 3.2.0

SpringFox3.0.0

在 SpringBoot2.7.3 版本的时候，项目使用的是 SpringFox3.0.0 的依赖，用于使用 Swagger，相关依赖如下：

xml 复制代码

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

项目编译没有问题，但是启动运行的时候报错 javax.servlet.http.HttpServletRequest ClassNotFoundException 异常。

这是因为 SpringFox3.0.0 底层有 Swagger2 和 Swagger3 两套一来，其中 Swagger2 底层依赖 javax 模块，但是在 SpringBoox3 的版本中已经彻底移除了 javax 模块，改为使用 jakarta ，所以才会报这个错误。

openapi3

解决方案：移除 Swagger2，改为完全使用 Swagger3。

在项目 pom.xml 中移除 SpringFox3.0.0 的依赖，改为使用 openapi3 的依赖，如下：

xml 复制代码

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
    <version>4.0.0</version>
</dependency>

Swagger 注解迁移

Swagger2 和 Swagger3 使用的是完全不同的两套注解，所以原本使用 Swagger2 相关注解的代码页需要完全迁移，改为使用 Swagger3 的注解。

Swagger2	Swagger3
@Api	@Tag
@ApiOperation	@Operation
@ApiImplicitParams	@Parameters
@ApiImplicitParam	@Parameter
@ApiModel	@Schema
@ApiModelProperty	@Schema
@ApiResponses	@ApiResponses
@ApiResponse	@ApiResponse
@ApiIgnore	@Hidden 或者其他注解的 hidden = true 属性

@Api

Swagger2 代码

java 复制代码

@Api(value = "用户操作接口", tags = "UserController")

Swagger3 代码

java 复制代码

@Tag(name = "UserController", description = "用户操作接口")

@ApiOperation

Swagger2 代码

java 复制代码

@ApiOperation(value = "分页查询用户数据")

Swagger3 代码

java 复制代码

@Operation(description = "分页查询用户数据")

@ApiImplicitParam

Swagger2 代码

java 复制代码

@ApiImplicitParams({
     @ApiImplicitParam(name = "currentPage", value = "当前页码", dataTypeClass = Integer.class, required = true),
     @ApiImplicitParam(name = "size", value = "当前页大小", defaultValue = "10", dataTypeClass = Integer.class),
     @ApiImplicitParam(name = "queryUser", value = "用户查询条件", dataTypeClass = User.class)
}

Swagger3 代码

java 复制代码

@Parameters({
    @Parameter(name = "currentPage", description = "当前页码", required = true),
    @Parameter(name = "size", description = "当前页大小", example = "10"),
    @Parameter(name = "queryUser", description = "用户查询条件")
})

@ApiModel

Swagger2 代码

java 复制代码

@ApiModel(value = "用户信息实体类")

Swagger3 代码

java 复制代码

@Schema(name = "用户信息实体类")

@ApiModelProperty

Swagger2 代码

java 复制代码

@ApiModelProperty(value = "用户名称")

Swagger3 代码

java 复制代码

@Schema(name = "用户名称")