如何在Spring Boot API网关中聚合多个微服务的OpenAPI 3接口文档

针对你需要将多个Spring Boot微服务的/v3/api-docs接口文档在Spring Boot API网关侧合并为单份OpenAPI文件的需求，有多种成熟的现成方案可选：

1. SpringDoc官方网关聚合方案（推荐，适配Spring全栈） #

SpringDoc官方原生支持网关侧的OpenAPI聚合能力，无需二次开发即可直接导出合并后的单份规范文件：

• 网关侧引入对应依赖：WebFlux栈（Spring Cloud Gateway默认栈）引入org.springdoc:springdoc-openapi-webflux-ui，Servlet网关引入org.springdoc:springdoc-openapi-ui
• 在application配置中添加各微服务的OpenAPI地址映射：

springdoc:
  api-docs:
    enabled: true
  swagger-ui:
    urls:
      - name: 用户服务
        url: /user/v3/api-docs
      - name: 订单服务
        url: /order/v3/api-docs

• 完成配置后直接调用网关的/v3/api-docs端点，即可获得所有微服务合并后的完整OpenAPI规范，官方默认处理了路径冲突、Schema组件去重、服务前缀拼接等适配逻辑。

2. 独立聚合工具方案 #

如果不想在网关引入额外依赖，可使用专门的OpenAPI合并工具实现：

• Java场景可引入openapi-merge轻量库，自行在网关开发一个简单的接口，拉取所有下游服务的OpenAPI JSON后调用库能力完成合并，支持自定义冲突处理规则（如重复Schema名自动加服务前缀）
• 有CI/CD流程的场景可在构建阶段用openapi-merger等工具定时拉取所有微服务的文档合并为静态文件，网关直接对外暴露该静态文件即可，对业务服务零侵入。

3. 自定义实现方案 #

如果有特殊的业务合并规则（如统一添加网关前缀、批量修改接口权限标识、过滤内部接口），可自行实现轻量聚合逻辑：

1. 配置定时任务定时拉取所有下游微服务的/v3/api-docs内容
2. 对paths、components.schemas等核心节点做合并，重复key添加服务名前缀避免冲突
3. 对外暴露自定义端点返回合并后的JSON即可，核心逻辑代码量不超过200行，灵活度最高。

内容的提问来源于stack exchange，提问作者lomasz