Springboot 3项目整合Knife4j接口文档
https://blog.csdn.net/zzm_0525/article/details/140256118
文章目录
- 前言
- 一、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官网推荐了SpringdocOpenApi 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注解的对比Swagger 2 OpenAPI 3 注解位置 作用
@Api @Tag(name = “接口类名”,description = “接口类描述”) Controller类 描述此controller的信息
@ApiOperation(value = “接口方法描述”) @Operation(summary =“接口方法描述”) Api端口方法 描述此Api的信息
@ApiImplicitParams @Parameters Api端口方法 描述参数信息
@ApiImplicitParam @Parameter(description=“参数描述”) Api方法的参数 描述参数信息
@ApiParam @Parameter(description=“参数描述”) Api方法的参数 -
@ApiIgnore @Parameter(hidden = true) 或 @Operation(hidden = true) 或 @Hidden - 用在各种地方，用于隐藏其Api
@ApiModel @Schema DTO类 用于Entity，以及Entity的属性上
@ApiModelProperty @Schema DTO属性 用于Entity，以及Entity的属性上
参考链接: 从 Springfox Swagger 2 迁移到 Springdoc Open API
三、使用步骤
1.Spring Boot 3.0项目中使用knife4j
在pom.xml文件中导入knife4j的依赖（本文springboot的版本是3.3.1）
<!-- Swagger3-knife4j依赖 -->
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
<version>4.5.0</version>
</dependency>其实现在就可以使用Knife4j了，暂不做其他配置，启动项目，浏览器输入 http://localhost:8080/doc.html 查看接口文档
由于我们没有进行任何的属性配置，所以看到的页面是knife4j的初始页面
- 在application.yml中添加knife4j相关配置
# knife4j的增强配置，不需要增强可以不配
knife4j:
enable: true # 开启knife4j,无需添加@EnableKnife4j注解
setting:
language: zh_cn #中文
swagger-model-name: 实体列表 #默认为: Swagger Models
basic: # 开启Swagger的Basic认证功能,默认是false
enable: true
username: admin
password: 123456
- 设置WebMvc相关配置（解决封装统一异常处理后doc.html无法打开的问题）
定义一个编码格式常量类，里面存储静态资源地址（封装起来便于使用和维护）
package com.patrick.blog.constant;
/**
* <p>
* 编码格式常量类
* </p>
*
* @author Patrick
* @since 2025-1-1
*/
public class SystemConstant {
/**
* Knife4j接口文档接口分组和分组路径
*/
public static class Knife4j {
/**
* 接口分组
*/
public static final String SECURITY = "权限管理";
public static final String SYSTEM = "系统管理";
/**
* 接口分组路径
*/
public static final String SECURITY_PATH = "com.patrick.blog.controller.security";
public static final String SYSTEM_PATH = "com.patrick.blog.controller.system";
}
/**
* 编码常量
*/
public static class Charset {
/**
* 编码格式设置
*/
public static final String JSON_TYPE_UTF8_CHARSET = "application/json;charset=UTF-8";
}
/**
* 允许匿名访问的静态资源路径列表
*/
public static final String[] STATIC_WITHE_PATH_LIST = new String[]{
"/",
"/js/**",
"/css/**",
"/img/**",
"/fonts/**",
"/index.html",
"/favicon.ico",
"/doc.html",
"/swagger-ui.html",
"/webjars/**",
"/swagger-resources/**",
"/v3/**"
};
/**
* 允许匿名访问的静态资源存放位置列表
*/
public static final String[] STATIC_WITHE_LOCATION_LIST = new String[]{
"classpath:/static/",
"classpath:/public/",
"classpath:/META-INF/resources/"
};
}
}定义系统配置类WebMvcConfig，由于knife4j接口文档属于静态资源，需将相关资源放行
package com.patrick.blog.config;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
import static com.patrick.blog.constant.SystemConstant.Permission.*;
/**
* <p>
* 设置WebMvc相关配置
* </p>
*
* @author Patrick
* @since 2025-1-1
*/
@Configuration
public class WebMvcConfig implements WebMvcConfigurer {
/**
* 解决resources下的静态资源无法访问
*
* @param registry 资源映射注册器
*/
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
// 静态资源映射
registry.addResourceHandler(STATIC_WITHE_PATH_LIST)
.addResourceLocations(STATIC_WITHE_LOCATION_LIST)
.setCachePeriod(0);
}
```}
4. 创建Knife4j的配置文件
该文件主要进行Knife4j的属性配置，如：标题、版本、作者信息、接口分组等
```java
package com.patrick.blog.config;
import io.swagger.v3.oas.models.info.Contact;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.License;
import org.springdoc.core.models.GroupedOpenApi;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import static com.patrick.blog.constant.SystemConstant.Knife4j.*;
/**
* <p>
* Knife4j配置类
* </p>
*
* @author Patrick
* @since 2025-1-1
*/
@Configuration
public class Knife4jConfig {
/**
* 创建权限分组api
*
*/
@Bean
public GroupedOpenApi securityApi() {
return createRestApi(SECURITY, SECURITY_PATH);
}
/**
* 创建系统分组api
*
*/
@Bean
public GroupedOpenApi systemApi() {
return createRestApi(SYSTEM, SYSTEM_PATH);
}
/**
* 创建api
*
* @param groupName 分组名称
* @param basePackage 包路径
* @return GroupedOpenApi
*/
public GroupedOpenApi createRestApi(String groupName, String basePackage) {
return GroupedOpenApi.builder()
.group(groupName) // 分组名称
.packagesToScan(basePackage) // 扫描的包路径
.pathsToMatch("/**") // 匹配所有路径
.addOpenApiCustomizer(openApi -> openApi.info(apiInfo())) // 设置api信息
.build();
}
/**
* api简介信息
*
* @return ApiInfo
*/
private Info apiInfo() {
return new Info()
.title("Patrick后台管理系统服务接口") // 标题
.description("Patrick后台管理系统服务接口文档...") // 描述
.version("1.0.0") // 版本号
.termsOfService("http://doc.xiaominfo.com") // 服务条款
.contact(new Contact().name("Patrick").url("https://github.com/Patrick-Luo-THR").email("patrick.luo@163.com")) // 联系人信息
.license(new License().name("Apache 2.0").url("http://www.apache.org/licenses/LICENSE-2.0.html")); // 许可证信息
}
}- 添加实体类信息
@Schema(description = “ ”)： 标记实体类属性
@Data
@TableName("t_user")
@Schema(description = "用户实体")
public class User implements Serializable {
@Schema(description = "用户id")
private Integer id;
@Schema(description = "用户昵称")
private String nickname;
@Schema(description = "用户名")
private String username;
@Schema(description = "用户密码")
private String password;
}- 在controller下新建security和system文件夹，添加相应接口进行测试
@Tag(name = “ ”)： 标记接口类别
@Operation(summary =“ ”)： 标记接口操作
创建(create) – 使用Post方法;
修改(update) – 使用Post方法;
删除(delete) – 使用Delete方法;
@RestController
@Tag(name = "用户管理")
@RequestMapping("/user")
public class UserController {
@Autowired
UserService userService;
/**
* 用户列表
* @return
*/
@Operation(summary = "用户列表")
@GetMapping("/list")
public JsonResult list() {
List<User> userList = userService.findAll();
return JsonResult.success().data("userList", userList);
}
}四、重启项目并访问接口文档
访问 http://localhost:8080/doc.html ，可以看到我们配置的属性已经在页面中显示出来了
五、Springboot启动类优化
每次都需要打开浏览器输入地址访问，对开发者很不友好，因此采取以下优化@Slf4j
@SpringBootApplication
public class BlogApplication {
public static void main(String[] args) {
ConfigurableEnvironment env = SpringApplication.run(BlogApplication.class, args).getEnvironment();
log.info("\n----------------------------------------------------------\n\t" +
"Application: '{}' is running Success! \n\t" +
"Local URL: \thttp://localhost:{}\n\t" +
"Document:\thttp://localhost:{}/doc.html\n" +
"----------------------------------------------------------",
env.getProperty("spring.application.name"),
env.getProperty("server.port"),
env.getProperty("server.port"));
}
}项目启动，控制台打印日志如下：
作者：Jeebiz 创建时间：2025-05-08 23:01
最后编辑：Jeebiz 更新时间：2025-05-08 23:06
最后编辑：Jeebiz 更新时间：2025-05-08 23:06
