SpringBoot 3.0 升级之 Swagger 升级
文章目录
- SpringFox3.0.0
- openapi3
- Swagger 注解迁移
- @Api
- @ApiOperation
- @ApiImplicitParam
- @ApiModel
- @ApiModelProperty
最近想尝试一下最新的 SpringBoot 项目，于是将自己的开源项目进行了一些升级。
- JDK 版本从
JDK8升级至JDK17。 - SpringBoot 版本从
SpringBoot 2.7.3升级到SpringBoot 3.2.0
SpringFox3.0.0
在 SpringBoot2.7.3 版本的时候，项目使用的是 SpringFox3.0.0 的依赖，用于使用 Swagger，相关依赖如下：
<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 的依赖，如下：
<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 代码
@Api(value = "用户操作接口", tags = "UserController")
- Swagger3 代码
@Tag(name = "UserController", description = "用户操作接口")
@ApiOperation
- Swagger2 代码
@ApiOperation(value = "分页查询用户数据")
- Swagger3 代码
@Operation(description = "分页查询用户数据")
@ApiImplicitParam
- Swagger2 代码
@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 代码
@Parameters({@Parameter(name = "currentPage", description = "当前页码", required = true),@Parameter(name = "size", description = "当前页大小", example = "10"),@Parameter(name = "queryUser", description = "用户查询条件")
})
@ApiModel
- Swagger2 代码
@ApiModel(value = "用户信息实体类")
- Swagger3 代码
@Schema(name = "用户信息实体类")
@ApiModelProperty
- Swagger2 代码
@ApiModelProperty(value = "用户名称")
- Swagger3 代码
@Schema(name = "用户名称")