1. 什么是 Knife4jKnife4j 是一款基于 SwaggerOpenAPI的 API 文档增强工具专为 Java 开发者设计尤其深度适配 Spring Boot 和 Spring Cloud 生态。它在前端 UI 界面、离线文档导出、接口调试体验等方面对原生 Swagger-UI 进行了大幅增强和优化是目前国内 Java 社区中最受欢迎的 API 文档生成与调试工具之一。2. 核心特性与优势相较于原生 Swagger-UIKnife4j 提供了更符合国内开发者习惯的强大功能更美观强大的 UI 界面提供多主题切换、接口分组树形展示、全局参数设置、离线文档下载等。增强的接口调试功能支持文件上传、接口响应结果格式化JSON/XML、全局请求头/参数管理。离线文档导出支持将文档一键导出为 Markdown、HTML、Word、PDF 等多种格式便于离线阅读和交付。OpenAPI 3.0 支持全面支持 OpenAPI 3.0 规范同时兼容 2.0。微服务聚合在 Spring Cloud 微服务架构下支持将多个服务的文档聚合到一个界面中统一查看和调试。安全性增强支持文档访问权限控制可配置登录认证。3. 快速入门Spring Boot 集成以下是在 Spring Boot 项目中集成 Knife4j 的基本步骤。3.1 添加依赖在项目的pom.xml文件中添加 Knife4j 的 Spring Boot Starter 依赖。dependency groupIdcom.github.xiaoymin/groupId artifactIdknife4j-openapi3-spring-boot-starter/artifactId version4.5.0/version /dependency注意如果你使用的是 Spring Boot 2.x 和 Swagger 2.x请使用knife4j-spring-boot-starter依赖。3.2 基础配置在application.yml或application.properties中进行简单配置。# application.yml 示例 spring: mvc: pathmatch: matching-strategy: ant_path_matcher # 解决 Spring Boot 2.6 与 Swagger 的兼容问题 knife4j: enable: true setting: language: zh_cn 生产环境建议关闭文档可通过配置动态控制 production: false3.3 创建配置类创建一个 Java 配置类来定义 Docket Bean这是 Swagger/OpenAPI 的核心配置。import io.swagger.v3.oas.models.OpenAPI; import io.swagger.v3.oas.models.info.Info; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; Configuration public class Knife4jConfig { Bean public OpenAPI customOpenAPI() { return new OpenAPI() .info(new Info() .title(项目 API 文档) .version(1.0) .description(这是一个基于 Spring Boot 和 Knife4j 的 API 文档示例) .contact(new io.swagger.v3.oas.models.info.Contact() .name(开发者) .email(devexample.com))); } }3.4 访问文档启动 Spring Boot 应用后可以通过以下两个地址访问文档Knife4j 增强 UIhttp://localhost:8080/doc.html原生 OpenAPI 规范 JSONhttp://localhost:8080/v3/api-docs打开doc.html即可看到功能丰富的 Knife4j 文档界面。4. 常用注解与 API 描述Knife4j 完全兼容 Swagger/OpenAPI 注解通过在 Controller 和 Model 上使用注解来生成详细的 API 文档。import io.swagger.v3.oas.annotations.Operation; import io.swagger.v3.oas.annotations.Parameter; import io.swagger.v3.oas.annotations.tags.Tag; import org.springframework.web.bind.annotation.*; RestController RequestMapping(/api/user) Tag(name 用户管理, description 用户相关的增删改查接口) // 接口分组标签 public class UserController { GetMapping(/{id}) Operation(summary 根据ID查询用户, description 通过用户ID获取用户详细信息) public User getUser(PathVariable Parameter(description 用户ID, required true) Long id) { // ... 业务逻辑 return new User(); } PostMapping Operation(summary 创建用户) public User createUser(RequestBody Parameter(description 用户信息, required true) User user) { // ... 业务逻辑 return user; } }import io.swagger.v3.oas.annotations.media.Schema; Schema(description 用户实体) public class User { Schema(description 用户ID, example 1001) private Long id; Schema(description 用户名, example 张三) private String name; Schema(description 年龄, example 25) private Integer age; // ... getters and setters }5. 高级功能与最佳实践5.1 接口分组多Docket对于大型项目可以将接口按模块分组展示。Bean Primary public GroupedOpenApi publicApi() { return GroupedOpenApi.builder() .group(public-apis) // 分组名称 .pathsToMatch(/api/public/**) .build(); } Bean public GroupedOpenApi adminApi() { return GroupedOpenApi.builder() .group(admin-apis) .pathsToMatch(/api/admin/**) .build(); }5.2 生产环境安全建议通过 Profile 或配置中心动态控制文档的开启与关闭。knife4j: enable: ${knife4j.enable:false} # 默认关闭通过环境变量开启 production: ${knife4j.production:true} # 生产环境设置为 true 会隐藏文档5.3 离线文档导出在 Knife4j 的 UI 界面右上角点击“离线文档”按钮可以选择导出为 Markdown、HTML、Word 等格式方便项目交付和归档。6. 总结Knife4j 极大地提升了 Spring Boot 项目 API 文档的生成、阅读和调试体验。它弥补了原生 Swagger-UI 在易用性和功能上的不足并通过丰富的增强特性成为 Java 后端开发的事实标准工具之一。掌握 Knife4j 的使用能够让你的项目文档更加专业、高效并改善前后端协作流程。