Spring Boot 2.x 集成 Knife4j (OpenAPI 3) 完整操作指南
本人在进行Java项目开发时，集成Knife4j 遇到了多方面的问题，在这里进行了一下记录总结。
文章目录
4.2 application.properties 配置（可选）
1. 环境准备
1.1 确认 Spring Boot 版本
确保使用 Spring Boot 2.x 版本（推荐 2.5.x - 2.7.x）
1.2 确认项目结构
- Maven 项目
- Spring Boot 2.x
- 需要 API 文档功能
2. 依赖配置
2.1 添加 Knife4j 依赖
在 pom.xml 中添加：
<properties> <!-- 推荐使用 4.1.0 或 4.3.0 --> <knife4j.version>4.3.0</knife4j.version> </properties> <dependencies> <!-- Knife4j OpenAPI3 增强依赖 --> <dependency> <groupId>com.github.xiaoymin</groupId> <artifactId>knife4j-openapi3-spring-boot-starter</artifactId> <version>${knife4j.version}</version> </dependency> </dependencies>2.2 移除旧版本 Swagger 依赖（如有）
确保移除以下旧依赖：
<!-- 需要移除的依赖 --> <!-- <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> </dependency> <dependency> <groupId>com.github.xiaoymin</groupId> <artifactId>knife4j-spring-boot-starter</artifactId> </dependency> -->注意：只保留Knife4j 依赖，其他的swagger相关依赖不要保留，否则会出现冲突！！！
3. 配置类设置
3.1 创建 Swagger 配置类
package com.example.config; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import io.swagger.v3.oas.models.OpenAPI; import io.swagger.v3.oas.models.info.Info; import io.swagger.v3.oas.models.info.Contact; import com.github.xiaoymin.knife4j.spring.annotations.EnableKnife4j; import lombok.extern.slf4j.Slf4j; import javax.annotation.PostConstruct; @Configuration @EnableKnife4j // 启用 Knife4j 增强功能 @Slf4j public class SwaggerConfig { @Bean public OpenAPI customOpenAPI() { log.info("=== 初始化 Knife4j OpenAPI3 配置 ==="); return new OpenAPI() .info(apiInfo()); } private Info apiInfo() { return new Info() .title("项目名称 API 文档") .description("项目描述信息") .termsOfService("http://localhost:8080/") .contact(new Contact() .name("开发团队") .url("http://localhost:8080/") .email("[email protected]")) .version("1.0"); } @PostConstruct public void init() { log.info("=== Knife4j OpenAPI3 配置初始化完成 ==="); log.info("文档地址: http://localhost:8080/doc.html"); log.info("OpenAPI JSON: http://localhost:8080/v3/api-docs"); } }3.2 可选：WebMvc 配置（解决静态资源问题）
package com.example.config; import org.springframework.context.annotation.Configuration; import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry; import org.springframework.web.servlet.config.annotation.WebMvcConfigurer; @Configuration public class WebMvcConfig implements WebMvcConfigurer { @Override public void addResourceHandlers(ResourceHandlerRegistry registry) { // 确保 Knife4j 的静态资源能够正常访问 registry.addResourceHandler("doc.html") .addResourceLocations("classpath:/META-INF/resources/"); registry.addResourceHandler("/webjars/**") .addResourceLocations("classpath:/META-INF/resources/webjars/"); } }若访问文档地址: http://localhost:8080/doc.html遇到Knife4j文档请求异常的错误提示（如下图），可以添加WebMvc 配置来进行解决，我出现这个错误就是添加WebMvc 配置解决的
4. 应用配置文件
4.1 application.yml 配置
# Spring 配置 spring: mvc: pathmatch: matching-strategy: ant_path_matcher # Spring Boot 2.6+ 必须配置 # Knife4j 配置 knife4j: enable: true setting: language: zh-CN # 中文界面4.2 application.properties 配置（可选）
# Spring 配置 spring.mvc.pathmatch.matching-strategy=ant_path_matcher # Knife4j 配置 knife4j.enable=true knife4j.setting.language=zh-CN5. 代码注解使用指南
5.1 控制器层注解
新版 OpenAPI3 注解
| OpenAPI3 注解 | 说明 | |
|---|---|---|
@Tag | 控制器分类 | |
@Operation | 接口操作 | |
@Parameter | 参数说明 | |
@ApiResponse | 响应说明 |
控制器示例：
@RestController @RequestMapping("/api/user") @Tag(name = "用户管理", description = "用户注册、登录、信息管理等接口") public class UserController { @PostMapping("/login") @Operation(summary = "用户登录", description = "通过用户名和密码登录系统") public Result<LoginVO> login( @Parameter(description = "登录参数", required = true) @Valid @RequestBody LoginDTO loginDTO) { // 业务逻辑 } }5.2 DTO/实体类注解
新版 OpenAPI3 注解
| OpenAPI3 注解 | 说明 | |
|---|---|---|
@Schema | 模型说明 | |
@Schema | 属性说明 |
DTO 示例：
@Data @Schema(description = "用户登录请求参数") public class LoginDTO { @Schema(description = "用户名", example = "admin", required = true) @NotBlank(message = "用户名不能为空") private String username; @Schema(description = "密码", example = "123456", required = true) @NotBlank(message = "密码不能为空") private String password; }5.3 响应对象注解
@Data @Schema(description = "通用返回结果") public class Result<T> { @Schema(description = "状态码", example = "200") private Integer code; @Schema(description = "提示信息", example = "成功") private String msg; @Schema(description = "返回数据") private T data; }6. 安全配置（如果使用 JWT 等安全框架）
在安全过滤器中放行 Knife4j 相关路径：
// 在 JWT 过滤器或安全配置中 private boolean isPublicUri(String uri) { return uri.startsWith("/doc.html") || uri.startsWith("/webjars/") || uri.startsWith("/v3/api-docs") || uri.startsWith("/favicon.ico") || uri.equals("/") || uri.startsWith("/swagger-resources"); }7. 访问和测试
7.1 文档访问地址
- Knife4j 增强文档: http://localhost:8080/doc.html
- OpenAPI JSON: http://localhost:8080/v3/api-docs
7.2 功能特性
- 接口分组管理
- 在线调试
- 接口搜索
- 离线文档导出
- 全局参数设置
- 接口权限控制
8. 常见问题及解决方案
8.1 页面无法访问
- 检查依赖版本：确认 Knife4j 版本兼容性
- 检查配置：确认
@EnableKnife4j注解已添加 - 清除缓存：浏览器 Ctrl+F5 强制刷新
8.2 接口文档不显示
- 检查注解：确认使用了正确的 OpenAPI3 注解
- 检查包扫描：确认控制器在 Spring 扫描路径内
- 检查安全配置：确认 Knife4j 路径已放行
8.3 静态资源加载失败
- 添加 WebMvc 配置：配置静态资源处理器
- 检查路径匹配策略：确认
ant_path_matcher配置
9. 版本兼容性参考
| Spring Boot 版本 | 推荐 Knife4j 版本 | 说明 |
|---|---|---|
| 2.5.x | 4.1.0 - 4.3.0 | 稳定兼容 |
| 2.6.x | 4.1.0 - 4.3.0 | 需配置 pathmatch |
| 2.7.x | 4.3.0 | 最新稳定 |
10. 最佳实践建议
- 统一响应格式：所有接口使用统一的 Result 包装类
- 详细接口描述：为每个接口和参数添加清晰的描述
- 分组管理：按模块对接口进行分组
- 版本控制：在 API 路径中包含版本号
- 权限控制：在文档中明确接口的访问权限要求
