背景
有一个项目升级到 Spring Boot 3.0，同事踩坑填坑花了点时间。遇到最大的一个坑就是 swagger 了，我顺便记录一下。
SpringFox
可以去它的官网看，SpringFox 已经有两三年没有更新了，属于被遗忘的项目。我去年也遇到 SpringFox 的问题，当时我用 Spring Boot 2.6，已经出现了不兼容报错的情况，所以退回了 2.5。今年是 Spring Boot 3.0，SpringFox 直接就别用了。
SpringDoc
SpringDoc 可以自动化生成 API 文档，它支持：（注意，本文所指均是 SpringDoc v2 版本）
- OpenAPI 3
- Spring Boot v3 (Java 17 & Jakarta EE 9)
- JSR-303, specifically for @NotNull, @Min, @Max, and @Size.
- Swagger-ui
- OAuth 2
- GraalVM native images
从 SpringFox 迁移
引入依赖
把原来的io.springfox、swagger 2相关的依赖都删除，然后添加 SpringDoc 的依赖：
<dependency> <groupId>org.springdoc</groupId> <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId> <version>2.1.0</version> </dependency>
替换注解
把原来 swagger 2 的注解替换成 swagger 3 的，springdoc-openapi-starter-webmvc-ui中已经包含了 swagger 3 的依赖。
@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")
之后 swagger 就可以在 http://server:port/context-path/swagger-ui.html 访问了。
简单例子
创建一个 controller：
@RestController
@RequestMapping("/test")
public class TestController {
@GetMapping("/greet")
@CrossOrigin
@Operation(summary = "say hello", description = "这里写描述")
public String greet(@RequestParam(required = false) String name) {
return "hello " + name;
}
}
访问 swagger 大概是这样：
具体的接口：
结语
上面只展示了最简单的使用，高级的用法和具体的配置在这里先不展开，需要时自己看官网文档。
发表评论