Spring Boot 2.x 集成 Knife4j (OpenAPI 3) 完整操作指南

本人在进行Java项目开发时，集成Knife4j 遇到了多方面的问题，在这里进行了一下记录总结。

---

文章目录

1. 环境准备

1.1 确认 Spring Boot 版本

1.2 确认项目结构

2. 依赖配置

2.1 添加 Knife4j 依赖

2.2 移除旧版本 Swagger 依赖（如有）

3. 配置类设置

3.1 创建 Swagger 配置类

3.2 可选：WebMvc 配置（解决静态资源问题）

4. 应用配置文件

4.1 application.yml 配置

4.2 application.properties 配置（可选）

5. 代码注解使用指南

5.1 控制器层注解

控制器示例：

5.2 DTO/实体类注解

DTO 示例：

5.3 响应对象注解

6. 安全配置（如果使用 JWT 等安全框架）

7. 访问和测试

7.1 文档访问地址

7.2 功能特性

8. 常见问题及解决方案

8.1 页面无法访问

8.2 接口文档不显示

8.3 静态资源加载失败

9. 版本兼容性参考

10. 最佳实践建议

---

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 {@Beanpublic 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("[e-mail]")).version("1.0");}@PostConstructpublic 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 {@Overridepublic 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: truesetting:language: zh-CN  # 中文界面

4.2 application.properties 配置（可选）

# Spring 配置
spring.mvc.pathmatch.matching-strategy=ant_path_matcher# Knife4j 配置
knife4j.enable=true
knife4j.setting.language=zh-CN

5. 代码注解使用指南

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 页面无法访问

1. 检查依赖版本：确认 Knife4j 版本兼容性

2. 检查配置：确认 @EnableKnife4j 注解已添加

3. 清除缓存：浏览器 Ctrl+F5 强制刷新

8.2 接口文档不显示

1. 检查注解：确认使用了正确的 OpenAPI3 注解

2. 检查包扫描：确认控制器在 Spring 扫描路径内

3. 检查安全配置：确认 Knife4j 路径已放行

8.3 静态资源加载失败

1. 添加 WebMvc 配置：配置静态资源处理器

2. 检查路径匹配策略：确认 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. 最佳实践建议

1. 统一响应格式：所有接口使用统一的 Result 包装类

2. 详细接口描述：为每个接口和参数添加清晰的描述

3. 分组管理：按模块对接口进行分组

4. 版本控制：在 API 路径中包含版本号

5. 权限控制：在文档中明确接口的访问权限要求