Springboot 3项目整合Knife4j接口文档（接口分组详细教程）

文章目录

• 前言
• 一、Spring Boot 3.0整合Knife4j
• 二、OpenApi 3注解的使用规范
• 三、使用步骤
• • 1.Spring Boot 3.0项目中使用knife4j
  • 2.在application.yml中添加knife4j相关配置
  • 3.设置WebMvc相关配置（解决封装统一异常处理后doc.html无法打开的问题）
  • 4.创建Knife4j的配置文件
  • 5.添加实体类信息
  • 6.在controller下新建security和system文件夹，添加相应接口进行测试
• 四、重启项目并访问接口文档
• 五、Springboot启动类优化

前言

springboot 3开始javax包改成了jakarta，而swagger-oas等包中依然使用的是javax，所以报错。另外springfox已经停止更新有段时间了，并且不支持OpenAPI 3标准，升级Springboot 3.0以后会有更多问题暴露出来。而SpringBoot 3只支持OpenAPI 3规范，因此Spring官网推荐了Springdoc

OpenApi 3的规范，目前针对Java的Spring Boot项目，主要支持的有2个版本：

• springfox 3.0.0： 同时兼容OpenAPI 2以及OpenAPI 3，但是停更很久了
• springdoc-openapi：兼容OpenAPI 3规范，更新速度频繁
• Knife4j：在只有的OpenAPI 3规范中，底层基础框架选择springdoc-openapi项目，针对Springfox 3.0.0版本会放弃

一、Spring Boot 3.0整合Knife4j

以下是一些常见的Spring Boot版本及其对应的Knife4j版本兼容推荐：

Spring Boot版本

Knife4j Swagger 2规范

Knife4j OpenAPI 3规范

1.5.x ~ 2.0.0

< Knife4j 2.0.0

>= Knife4j 4.0.0

2.0 ~ 2.2

Knife4j 2.0.0 ~ 2.0.6

>= Knife4j 4.0.0

2.2.x ~ 2.4.0

Knife4j 2.0.6 ~ 2.0.9

>= Knife4j 4.0.0

2.4.0 ~ 2.7.x

>= Knife4j 4.0.0

>= Knife4j 4.0.0

>= 3.0

>= Knife4j 4.0.0

>= Knife4j 4.0.0

参考文档：关于Knife4j适配不同Spring Boot版本的说明文档

项目配置：

JDK：23

SpringBoot：3.3.1

Knife4j：4.5.0

温馨提示：

二、OpenApi 3注解的使用规范

• Swagger 3(OpenApi 3) 注解与Swagger 2注解的对比
</