什么是Springfox

Automated JSON API documentation for API's built with Spring

官网地址：springfox.io

什么是Springdoc

springdoc-openapi java library helps to automate the generation of API documentation using spring boot projects.

官网地址：https://springdoc.org/v2/

注意：使用的是V2版本，这个版本支持springboot3.0

为什么改用springdoc

之前springboot3.0之前我用的都是Springfox来集成Swagger管理我们的API接口文档，这也就是Springfox和Springdoc最主要的功能。因为Springfox已经停止更新有段时间了，升级Springboot3.0以后会有更多问题暴露出来。Spring官网推荐了Springdoc，应该不会短时间停更，所以改用Springdoc

具体实现

Springdoc使用也很简单，基本上也是开箱即用，不需要任何的配置，直接就可以使用。

首先添加依赖：

   <dependency>
      <groupId>org.springdoc</groupId>
      <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
      <version>2.0.2</version>
   </dependency> 

     <dependency>
      <groupId>org.springdoc</groupId>
      <artifactId>springdoc-openapi-starter-webmvc-api</artifactId>
      <version>2.0.2</version>
   </dependency>

两个依赖添加上，我们就可以直接使用Swagger3的注解了

@Tag(name = "用户管理")
@RestController
public class UserController {

    private final Logger logger = LoggerFactory.getLogger(UserController.class);

    @Operation(summary = "列表")
    @PostMapping("list")
    public ResultJson list() {
        ...
        return ResultJson.success();
    }

    @Operation(summary ="新增")
    @PostMapping("add")
    public ResultJson add(AdminRole AdminRole) {
       ...
        return ResultJson.success();
    }

    @Operation(summary ="修改")
    @PostMapping("update")
    public ResultJson update(AdminRole AdminRole) {
         ...
        return ResultJson.success();
    }

    @Operation(summary ="删除")
    @PostMapping("delete")
    public ResultJson delete(Integer id) {
           ...
        return ResultJson.success();
    }
}

从Springfox迁移过来的，需要修改注解：

• @Api → @Tag

• @ApiIgnore → @Parameter(hidden = true) or @Operation(hidden = true) or @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")

目前只用到了这些，这样启动项目就可以看到熟悉的界面了，后面用到什么再补充。地址：http://ip:port/context-path/swagger-ui.html