SpringBoot 3.5 集成 Knife4j 4.3 步骤

目录

一、 核心组件与关系介绍

二、 Knife4j 简介与资源

三、 Spring Boot 3.5 单体应用集成步骤

1. 环境准备

2. 引入 Maven 依赖

3. 配置文件 (application.yml)

4. 初始化配置 @Configuration

5. 注解示例

6 访问验证

四、 Spring Cloud Gateway 集成方案

1. 网关服务 (Gateway) 配置

2. 子微服务 (Service) 配置

3. 访问方式

---

避坑指南：还在用 SpringFox？快换成这位“天选之子”吧！

各位小伙伴，有没有遇到过这种让人抓狂的场面：兴冲冲地把 Spring Boot 2 升级到 Spring Boot 3，一启动，嘿，项目跑起来了！正准备给自己点个赞，结果一打开 Swagger 页面——404 空白。

这时候你才恍然大悟：原来当年陪我们渡过了无数个 CRUD 日夜的 SpringFox，早在 2020 年就悄悄停更了。它不仅跟不上 OpenAPI 3 的新潮规范，更致命的是，它底层死死抱住的 javax.* 包，在 Spring Boot 3 时代已经被彻底连根拔起，换成了 jakarta.* 。

简单来说，这不是你代码写得有问题，而是时代的眼泪。面对这种“版本刺客”，硬刚肯定是不现实的。既然官宣分手，咱们就得收拾心情，寻找新的幸福——也就是今天的主角：SpringDoc。而 Knife4j 的底层就是SpringDoc。

为什么我说它是“天选之子”？

• 无缝衔接：它是基于 OpenAPI 3 规范量身定制的，对 Spring Boot 3 甚至 WebFlux 都是原生级支持，丝滑得就像德芙。

• 极简主义：以前用 SpringFox 时，那一堆繁琐的 Docket 配置是不是让你很头疼？换成 SpringDoc 后，很多时候你只需要引入一个 Starter 依赖，连配置文件都不用写就能直接起飞。

• 社区活跃：不像前任那样玩失踪，SpringDoc 社区更新非常活跃，遇到 Bug 也有人管，这才是长长久久的靠谱之选。

一、 核心组件与关系介绍

在微服务架构中，API 文档工具通常分为“规范”、“生成器”和“展示层”三个部分。以下是它们的具体分工与关系：

组件	角色定位	核心作用	与 Knife4j 的关系
Swagger (OpenAPI 3)	接口规范	定义了一套用于描述 API 接口的标准（如路径、参数、返回值）。	Knife4j 完全遵循 OpenAPI 3.0 规范生成文档。
SpringDoc	规范实现	扫描 Spring Boot 代码中的注解 （如@Tag,@Operation） ，自动生成符合 OpenAPI 规范的 JSON 数据。 SpringDoc 自带原生 Swagger UI。	底层依赖。Knife4j 4.x 已内置 SpringDoc，负责数据的生产。
Knife4j	UI 增强层	基于 SpringDoc 提供的数据，渲染出美观、交互性更强的文档界面。	上层封装。在 SpringDoc 基础上提供了文档增强、离线导出等功能。

二、 Knife4j 简介与资源

Knife4j是一个为 Java MVC 框架集成 Swagger 生成 API 文档的增强解决方案。其前身是swagger-bootstrap-ui，旨在提供更符合国人习惯的接口文档体验。

• 核心作用：

1. 1. 文档说明：根据代码注解自动生成详尽的接口文档，包含请求/响应示例。
   2. 在线调试：提供强大的接口调试功能，支持全局参数、动态参数修改。
   3. 离线文档：支持导出 Markdown、HTML、Word 等格式的离线文档，方便交付。
   4. 界面优化：提供现代化的 UI 界面，支持深色模式、接口搜索与排序。

• 官方资源：

• • 官方文档：https://doc.xiaominfo.com/
  • 源码地址：https://gitee.com/xiaoym/knife4j

三、 Spring Boot 3.5 单体应用集成步骤

1. 环境准备

• JDK：17 及以上（Spring Boot 3.x 强制要求）
• Spring Boot：3.5.9
• Knife4j：4.3.0

2. 引入 Maven 依赖

在pom.xml中添加 Knife4j 的 Starter。该依赖已内置 SpringDoc，无需再单独引入 Swagger 相关包。

<dependency> <groupId>com.github.xiaoymin</groupId> <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId> <version>4.3.0</version> </dependency>

依赖包 knife4j-openapi3-jakarta-spring-boot-starter 包含子依赖包主要有:

依赖包	描述	核心作用
knife4j-openapi3-ui	Knife4j 的 UI 核心	提供增强的 Web 界面 (/doc.html)，包含文档渲染、接口调试、全局参数、离线导出等功能。
knife4j-core	Knife4j 工具模块	提供工具类、模型定义、核心工具链等底层支持。
springdoc-openapi-starter-webmvc-ui	SpringDoc WebMVC 集成与 UI	提供原生的 Swagger UI (/swagger-ui.html)，是 SpringDoc 自动配置的入口。
springdoc-openapi-starter-webmvc-api	SpringDoc WebMvc API 支持	提供对 Spring WebMVC 的底层支持，包含请求/响应处理、参数解析等。
springdoc-openapi-starter-webmvc-common	SpringDoc WebMvc 通用模块	包含 SpringDoc 的通用工具类和核心逻辑，是 API 模块的基础。
swagger-annotations-jakarta	OpenAPI 注解库 (Jakarta)	提供jakarta命名空间版本的 OpenAPI 注解，如@Tag,@Operation,@Schema等。
swagger-models-jakarta	OpenAPI 模型库 (Jakarta)	提供jakarta命名空间版本的 OpenAPI 数据模型，如Info,Contact,OpenAPI等。
swagger-ui	Swagger UI 前端资源	包含 Swagger UI 的所有前端静态资源（HTML, JS, CSS），被springdoc-openapi-starter-webmvc-ui所依赖。

3. 配置文件 (application.yml)

配置 SpringDoc 的扫描规则和 Knife4j 的增强特性。

# SpringDoc 原生配置 springdoc: swagger-ui: enabled: true path: /swagger-ui.html tags-sorter: alpha operations-sorter: alpha api-docs: enabled: true path: /v3/api-docs group-configs: - group: default paths-to-match: '/**' packages-to-scan: com.example.controller # Knife4j 增强配置 knife4j: enable: true setting: language: zh_cn enable-swagger-models: true swagger-model-name: 实体类列表

4. 初始化Bean配置 @Configuration

/** * OpenApi3在线接口文档组件初始化 */ @Slf4j @Configuration(proxyBeanMethods = false) @ConditionalOnProperty(name = "springdoc.api-docs.enabled", matchIfMissing = true) public class OpenApi3Config { @Bean public OpenAPI springDocOpenAPI() { return new OpenAPI(SpecVersion.V30).info(new Info() .title("API文档") .description("简介") .version("v1.0")) // 作用于整个 OpenAPI 文档，公共请求头参数设置 // 现象：在 knife4j 菜单出现 Authorize 菜单 .components(new Components() .addSecuritySchemes("Authorization", new SecurityScheme() .name("Authorization") .in(SecurityScheme.In.HEADER) .type(SecurityScheme.Type.APIKEY)) .addSecuritySchemes("TENANT-ID", new SecurityScheme() .name("TENANT-ID") .in(SecurityScheme.In.HEADER) .type(SecurityScheme.Type.APIKEY))); } /** * 作用于每个接口，请求头中自动添加了head参数（Authorization、TENANT-ID） */ @Bean @ConditionalOnMissingBean public HeaderGlobalOperationCustomizer globalHeaderAdder() { return new HeaderGlobalOperationCustomizer(); } }

公共设置效果图

作用于每个接口 HeaderGlobalOperationCustomizer.java

/** * 作用于每个接口，请求头中自动添加了head参数（Authorization、TENANT-ID） */ public class HeaderGlobalOperationCustomizer implements GlobalOperationCustomizer { @Override public Operation customize(Operation operation, HandlerMethod handlerMethod) { operation.addSecurityItem(new SecurityRequirement() .addList("Authorization") .addList("TENANT-ID")); return operation; } }

作用每个接口的效果图

5. 注解示例

Spring Boot 3.x 使用 OpenAPI 3 规范注解，与旧版 Swagger 2 不同。

注解	作用位置	描述	示例/替代旧注解
@Tag	Controller 类	API 分组标签	替代@Api
@Operation	Controller 方法	单个接口的详细描述	替代@ApiOperation
@Parameter	方法参数	描述单个参数	替代@ApiParam
@Schema	模型类/字段	描述数据模型/字段	替代@ApiModel,@ApiModelProperty
@Parameters	方法	多个参数的容器	包含多个@Parameter

控制器Controller

import io.swagger.v3.oas.annotations.Operation; import io.swagger.v3.oas.annotations.Parameter; import io.swagger.v3.oas.annotations.tags.Tag; @RestController @RequestMapping("/api/users") @Tag(name = "用户管理") public class UserController { @GetMapping("/{id}") @Operation(summary = "根据ID查询用户") public String getUser(@Parameter(description = "用户ID", required = true) @PathVariable Long id) { return "User " + id; } }

实体Bean

@Schema(description = "用户信息") @Data @Builder @NoArgsConstructor @AllArgsConstructor public class UserInfo { /** * 中文名 */ @Schema(description = "中文名") private String name; }

6 访问验证

启动项目后，访问以下地址：

• Knife4j 文档地址：http://localhost:8080/doc.html
• 原生 Swagger 地址：http://localhost:8080/swagger-ui.html

效果图

四、 Spring Cloud Gateway 集成方案

在微服务架构中，通常希望在网关层聚合所有微服务的接口文档，无需逐个访问子服务。

1. 网关服务 (Gateway) 配置

在 Gateway 模块中引入聚合依赖：

<dependency> <groupId>com.github.xiaoymin</groupId> <artifactId>knife4j-gateway-spring-boot-starter</artifactId> <version>4.3.0</version> </dependency> <!-- 这里特别注意，只能引入 springdoc-openapi-starter-webflux-api ， 不要引入 springdoc-openapi-starter-webflux-ui, 不然在 doc.html 会出现微服务下拉列表无法获取数据 --> <dependency> <groupId>org.springdoc</groupId> <artifactId>springdoc-openapi-starter-webflux-api</artifactId> <version>2.8.15</version> </dependency> <dependency> <groupId>org.springframework.cloud</groupId> <artifactId>spring-cloud-starter-gateway-server-webflux</artifactId> <version>4.3.3</version> </dependency>

在application.yml中开启服务发现模式聚合：

# 第二种配置方式：自动发现 knife4j: gateway: enabled: true # 指定聚合模式为服务发现（基于注册中心如 Nacos/Eureka） strategy: discover discover: enabled: true version: openapi3 # 第二种配置方式：手动配置 knife4j: gateway: enabled: true strategy: manual operations-sorter: order routes: - name: 用户服务 context-path: /user url: /user/v3/api-docs/default - name: 订单管理 context-path: /order url: /order/v3/api-docs/default

2. 子微服务 (Service) 配置

确保每个业务微服务都按照第三部分的步骤引入了knife4j-openapi3-jakarta-spring-boot-starter并正确配置了packages-to-scan。

3. 访问方式

启动网关和各个微服务后，直接访问网关的地址即可查看聚合文档：

http://网关IP:网关端口/doc.html

效果图