SpringBoot3.5集成Knife4j4.3的详细步骤

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

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

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

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

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

• 无缝衔接：基于 OpenAPI 3 规范量身定制，对 Spring Boot 3 甚至 WebFlux 都是原生级支持，丝滑得就像德芙。
• 极简主义：以前用 SpringFox 时，那一堆繁琐的 Docket 配置是不是很头疼？换成 SpringDoc 后，很多时候只需要引入一个 Starter 依赖，连配置文件都不用写就能直接起飞。
• 社区活跃：不像前任那样玩失踪，SpringDoc 社区更新非常活跃，遇到 Bug 也有人管，这才是长长久久的靠谱之选。

一、 核心组件与关系介绍

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

二、 Knife4j 简介与资源

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

• 核心作用：
  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. 引入 Ma ven 依赖

在 pom.xml 中加一个依赖。这个依赖已经内置 SpringDoc，所以不需要再单独引入 Swagger 相关包。

    com.github.xiaoymin
    knife4j-openapi3-jakarta-spring-boot-starter
    4.3.0

来看看这个依赖包里包含了哪些子依赖：

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. 初始化配置 @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"))
        // 配置Authorizations
        .components(new Components()
                    .addSecuritySchemes("Authorization", new SecurityScheme().name("Authorization").in(SecurityScheme.In.HEADER).type(SecurityScheme.Type.APIKEY))
                    .addSecuritySchemes("TenandId", new SecurityScheme().name("TenandId").in(SecurityScheme.In.HEADER).type(SecurityScheme.Type.APIKEY)));
    } 
}

5. 注解示例

Spring Boot 3.x 使用 OpenAPI 3 规范注解，和旧版 Swagger 2 差别不小。

控制器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 模块中引入聚合依赖：

    com.github.xiaoymin
    knife4j-gateway-spring-boot-starter
    4.3.0



    org.springdoc
    springdoc-openapi-starter-webflux-api
    2.8.15 


    org.springframework.cloud
    spring-cloud-starter-gateway-server-webflux
    4.3.3 

在 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

效果图