【超详细】springboot + springdoc-openapi + knife4j 集成案例

springdoc-openapi 简介

springdoc-openapijava库有助于使用 spring boot 项目自动生成 API 文档。 springdoc-openapi通过在运行时检查应用程序以根据 spring 配置、类结构和各种注释推断 API 语义来工作。

自动生成 JSON/YAML 和 HTML 格式 API 的文档。可以使用 swagger-api 注释通过注释来完成此文档。

该库支持：

• OpenAPI3
• SpringBoot (v1, v2 and v3)
• JSR-303, specifically for @NotNull, @Min, @Max, and @Size.
• Swagger-ui
• OAuth 2
• GraalVM 原生镜像

为什么使用 springdoc-openapi

由于之前项目一直使用的是springfox3.0来集成swagger管理API接口文档，但目前springfox已经停止维护了。最近在升级底层框架时看到spring官方推荐使用springdoc，在自己一步一步查找相关资料时，发现国内对于这块的参考资料较少，也不全面。故写此篇文章来帮助大家快速集成。

Knife4j简介

Knife4j是一个集Swagger2和OpenAPI3为一体的增强解决方案。

开始集成

Maven引入

首先在maven里引入springdoc-openapi：

    org.springdoc
    springdoc-openapi-ui
    1.6.15

复制代码

注释的区别

这里需要注意，我们要用swagger3注释替换swagger2注释（它已经包含在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