Spring Cloud Gateway 整合 Knife4j 聚合文档：避坑指南与解决方案（Spring Boot 3.X）

最新！！！Gateway 整合 Knife4j 聚合文档：避坑指南与解决方案（Spring Boot 3.X）😎

在微服务架构中，通过 Gateway 网关聚合各子服务的 API 文档是提升团队协作效率的重要手段。实际配置中，discover（服务发现）和 manual（手动配置）两种模式各有适用场景，本文将详解两种模式的配置要点，重点解决版本适配、路径转发等核心问题，适配 Spring Boot 3 环境🚀。

Spring Cloud Gateway网关聚合官方地址：https://doc.xiaominfo.com/docs/middleware-sources/spring-cloud-gateway/spring-gateway-introduction

一、环境与依赖：Spring Boot 3 专属配置 🛠️

Spring Boot 3 基于 Jakarta EE 规范，需使用 Knife4j 专门适配的版本，避免依赖冲突哦～

1. 子服务依赖（Spring Boot 3）

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

• 作用 ：生成 OpenAPI 3.0 规范文档（默认路径 /v3/api-docs），适配 Jakarta 注解（如 jakarta.validation）✅。

2. 网关服务依赖（Spring Boot 3）

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-gateway-spring-boot-starter</artifactId>
    <version>4.4.0</version>
</dependency>

• 作用 ：支持网关层文档聚合，兼容 discover 和 manual 两种模式🌟。

二、discover 模式（推荐）：服务发现自动聚合 🤖

discover 模式通过注册中心自动识别子服务并聚合文档，适合服务数量多、动态扩展的场景，需重点解决版本适配问题哦～

1. 核心配置：指定 version: openapi3 适配 OpenAPI 3.0

问题 ：默认 discover 模式使用 version: swagger2，指向 /v2/api-docs，但 Spring Boot 3 子服务默认生成 /v3/api-docs，导致 404 😱。

解决方案 ：明确指定版本为 openapi3：

knife4j:
  gateway:
    enabled: true  # 开启聚合功能
    strategy: discover  # 服务发现模式
    discover:
      enabled: true  # 启用服务发现
      version: openapi3  # 关键：适配 OpenAPI 3.0，自动请求 /v3/api-docs 🎯

2. 路由转发：必须添加路径重写

问题 ：网关路由前缀（如 /order）会导致请求 http://网关/order/v3/api-docs 被转发到子服务的 /order/v3/api-docs（子服务实际路径为 /v3/api-docs）😵。

解决方案 ：配置 RewritePath 过滤器去除前缀：

spring:
  cloud:
    gateway:
      routes:
        - id: order-service
          uri: lb://order-service  # 与注册中心服务名一致
          predicates:
            - Path=/order/**
          filters:
            - RewritePath=/order/(?<segment>.*), /$\{segment}  # /order/v3/api-docs → /v3/api-docs ✨
        
        - id: stock-service
          uri: lb://stock-service
          predicates:
            - Path=/stock/**
          filters:
            - RewritePath=/stock/(?<segment>.*), /$\{segment}

三、manual 模式：手动配置（兼容 Swagger2/OpenAPI3）📝

manual 模式需手动指定每个服务的文档路径，适合服务数量少、需精确控制的场景。需注意其默认适配 Swagger2 的问题哦～

1. 核心问题：默认适配 Swagger2（/v2/api-docs）

问题 ：manual 模式默认按 Swagger2 规范请求 /v2/api-docs，若子服务使用 OpenAPI 3.0（/v3/api-docs），需手动指定路径🔍。

2. 解决方案：明确指定 OpenAPI 3.0 路径

knife4j:
  gateway:
    enabled: true
    strategy: manual  # 手动配置模式
    routes:
      - name: 订单服务
        service-name: order-service  # 与注册名一致
        url: /order/v3/api-docs  # 明确指定 OpenAPI 3.0 路径 📌
        context-path: /order  # 接口路径自动添加 /order 前缀
        
      - name: 库存服务
        service-name: stock-service
        url: /stock/v3/api-docs
        context-path: /stock

3. 路由转发：与 discover 模式一致

需同样配置 RewritePath 过滤器，确保路径转发正确（同上文路由配置）✅。

四、两种模式的对比与适用场景 🆚

模式	优势	劣势	适用场景
discover	自动聚合，无需手动维护服务列表 🚀	依赖注册中心，版本配置需统一	服务数量多、动态扩展频繁
manual	精确控制，兼容多版本规范 🎯	新增服务需手动配置	服务数量少、需定制化文档路径

五、通用坑点与解决方案 💡

1. 服务名不匹配

问题 ：网关 service-name 与注册中心服务名不一致，导致服务无法发现❌。
解决 ：子服务 spring.application.name 需与网关 service-name 完全一致（如均为 order-service）✅。

2. 接口响应非 JSON 格式

问题 ：子服务接口返回纯文本/HTML，导致文档解析失败📄。
解决 ：使用 @RestController，确保响应为 JSON 格式（推荐统一封装 Result 响应体）📦。

3. 依赖版本错误

问题 ：Spring Boot 3 误用传统依赖（如 knife4j-spring-boot-starter），导致 javax 类找不到❌。
解决：严格使用 Jakarta 专属依赖（见上文"环境与依赖"部分）🔧。

六、验证流程 ✅

1. 子服务文档验证 ：访问 http://子服务IP:端口/v3/api-docs，确认返回 JSON📌。
2. 网关转发验证 ：访问 http://网关IP/order/v3/api-docs，确认返回与子服务一致的 JSON🔄。
3. 聚合文档验证 ：访问 http://网关IP/doc.html，检查是否显示所有服务接口🗂️。

总结 🎉

Spring Boot 3 整合 Knife4j 聚合文档的核心是"版本适配"与"路径对齐"：

• discover 模式通过 version: openapi3 适配 OpenAPI 3.0，配合路径重写实现自动聚合；
• manual 模式需手动指定 /v3/api-docs 路径，适合精细化配置；
• 无论哪种模式，都需确保服务名一致、接口返回 JSON 格式。

按此配置，可高效解决 404、版本冲突等问题，实现微服务文档的统一管理🌟！

如果各位大佬发现有不对的地方，或者有更优的解决方案，非常欢迎在评论区指正和交流 ------ 毕竟技术之路就是在不断踩坑、填坑和分享中共同进步的嘛！希望这篇指南能帮到正在为网关聚合文档头疼的小伙伴们，少走弯路，高效开发～ 😊