【超详细】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：

<dependency> <groupId>org.springdoc</groupId> <artifactId>springdoc-openapi-ui</artifactId> <version>1.6.15</version> </dependency> 复制代码

注释的区别

这里需要注意，我们要用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") -> @