【超详细】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") -> @ApiResponse(responseCode = "404", description = "foo") 复制代码

以下举几个简单的：

Controller：

@Tag(name = "用户接口") @RestController @RequestMapping("sys/user") public class SysUserController { @Resource private ISysUserService sysUserService; @Operation(summary = "分页查询") @GetMapping("page") public AjaxResult queryPage(@ParameterObject SysUserPageDTO dto) { PageInfo page = sysUserService.queryPage(dto); return AjaxResult.success(page); } @Operation(summary = "详情") @GetMapping("{id}") public AjaxResult queryInfo(@PathVariable Long id) { SysUserDTO dto = sysUserService.queryById(id); return AjaxResult.success(dto); } @Operation(summary = "新增") @PostMapping public AjaxResult save(@RequestBody SysUserDTO dto) { Long id = sysUserService.saveInfo(dto); return AjaxResult.success(id); } } 复制代码

POST请求的DTO:

@Schema(description = "用户 数据传输对象") @Data @Accessors(chain = true) public class SysUserDTO implements Serializable { @Schema(description = "ID") private Long id; @Schema(description = "用户名") private String userName; @Schema(description = "真实姓名") private String realName; @Schema(description = "密码") private String password; @Schema(description = "性别（0男，1女）") private Integer sex; @Schema(description = "电话号码") private String phone; @Schema(description = "状态（0停用，1正常）") private Integer status; } 复制代码

❗ 如果你使用一个对象来封装你GET请求的参数，会将你的参数封装为一个json，这不是我们想要的：

添加图片注释，不超过 140 字（可选）

要解决这样的问题，有两种解决方法（感谢@nano发现及解决的问题）：

方法一（推荐）：

在官方文档里有这么一句话：“如果您使用一个对象来捕获多个请求查询参数，请注释该方法参数 @ParameterObject”。所以你应该在你get请求封装的对象前加注解 @ParameterObject，同时应该在对象里的参数注解使用 @Parameter，而不是 @Scheme。

GET接口：

@Operation(summary = "分页查询") @GetMapping("page") public AjaxResult queryPage(@ParameterObject SysUserPageDTO dto) { PageInfo page = sysUserService.queryPage(dto); return AjaxResult.success(page); } 复制代码

GET请求封装的DTO：

@Data @EqualsAndHashCode(callSuper = true) @Accessors(chain = true) public class SysUserPageDTO extends BasePageDTO { @Parameter(description = "用户名") private String username; } 复制代码

方法二（不推荐）：

添加配置（添加此配置后，就不需要添加额外的@ParameterObject和@Parameter注解）：

❗ 注：这个配置在最新版（1.6.15）有个bug，当你使用这个配置以后再用@Valid注解，配置会失效，待官方解决，所以推荐方法一（PS：官方已修复了该问题，下个版本应该会解决）。

spring-doc: default-flat-param-object: true 复制代码

配置

配置文件，更多配置请看：springdoc 核心配置

springdoc: api-docs: # 是否开启接口文档 enabled: true swagger-ui: # 持久化认证数据，如果设置为 true，它会保留授权数据并且不会在浏览器关闭/刷新时丢失 persistAuthorization: true 复制代码

配置文档:

❗ 这里我更推荐将文档标题、作者等信息写到application里，然后通过@ConfigurationProperties引入，会更优雅

@Configuration @AutoConfigureBefore(SpringDocConfiguration.class) public class OpenApiConfig { private static final String TOKEN_HEADER = "Authorization"; @Bean public OpenAPI openApi() { return new OpenAPI() .components( new Components().addSecuritySchemes(TOKEN_HEADER, new SecurityScheme() .type(SecurityScheme.Type.APIKEY) // 这里配置 bearer 后，你的请求里会自动在 token 前加上 Bearer .scheme("bearer") .bearerFormat("JWT") ).addParameters(TOKEN_HEADER, new Parameter() .in("header") .schema(new StringSchema()) .name(tokenHeader) )) .info( new Info() .title("文档标题") .description("文档描述") .contact(new Contact().name("作者").email("邮箱").url("可以写你的博客地址或不填")) // 参考 Apache 2.0 许可及地址，你可以不配此项 .license(new License().name("Apache 2.0").url("https://www.apache.org/licenses/LICENSE-2.0.html")) .version("0.1") ) // 引入外部的文档，我这里引得是 springdoc 官方文档地址，你可以不配此项 .externalDocs(new ExternalDocumentation() .description("SpringDoc Full Documentation") .url("https://springdoc.org/") ); } /** * GroupedOpenApi 是对接口文档分组，类似于 swagger 的 Docket * * @return */ @Bean public GroupedOpenApi authApi() { return GroupedOpenApi.builder() // 组名 .group("认证接口") // 扫描的路径，支持通配符 .pathsToMatch("/login") // 扫描的包 .packagesToScan("com.demo.controller.auth") .build(); } @Bean public GroupedOpenApi sysApi() { return GroupedOpenApi.builder() .group("系统接口") .pathsToMatch("/sys/**") // 添加自定义配置，这里添加了一个用户认证的 header，否则 knife4j 里会没有 header .addOperationCustomizer((operation, handlerMethod) -> operation.security( Collections.singletonList(new SecurityRequirement().addList(TOKEN_HEADER))) ) .build(); } } 复制代码

访问文档

配置完成之后，就可以访问文档地址：http://localhost:${port}/${context-path}/swagger-ui/html.index

❗ 如果你加入了拦截器或引入了spring-security等权限框架，需要放通文档地址及静态资源：

- /**/*.html - /**/*.css - /**/*.js - /**/api-docs/** 复制代码

至此一个简单的接口文档就生成了，是不是很简单

添加图片注释，不超过 140 字（可选）

集成knife4j

Maven引入

在maven里引入knife4j

❗ 在knife4j@4.1.0里已经引入了springfox-openapi-ui@1.6.15，注意jar包冲突。

<dependency> <groupId>com.github.xiaoymin</groupId> <artifactId>knife4j-openapi3-spring-boot-starter</artifactId> <version>4.1.0</version> </dependency> 复制代码

❗ 如果你使用的是SpringBoot3，需要注意：

• Spring Boot 3 只支持OpenAPI3规范

• Knife4j提供的starter已经引用springdoc-openapi的jar，开发者需注意避免jar包冲突

• JDK版本必须 >= 17

而且需要引入这个包：

<dependency> <groupId>com.github.xiaoymin</groupId> <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId> <version>4.0.0</version> </dependency> 复制代码

访问文档地址

然后你就可以直接访问文档地址了：http://localhost:${port}/${context-path}/doc.html

添加图片注释，不超过 140 字（可选）

至此我们就集成完了，有其他疑问欢迎在评论区提出来

                                                                                                           资源获取：
大家 点赞、收藏、关注、评论啦 、 查看👇🏻👇🏻👇🏻 微信公众号获取联系方式👇🏻👇🏻👇🏻
精彩专栏推荐订阅：在 下方专栏👇🏻👇🏻👇🏻👇🏻
每天学四小时：Java+Spring+JVM+分布式高并发，架构师指日可待

————————————————
版权声明：本文为CSDN博主「写代码的珏秒秒」的原创文章，遵循CC 4.0 BY-SA版权协议，转载请附上原文出处链接及本声明。
原文链接：https://blog.csdn.net/m0_63437643/article/details/133275558