如何实现Spring Boot微服务Swagger/OpenAPI UI单地址统一访问

以下方案不需要修改现有16个微服务的业务代码，最快10分钟就能搭好统一访问入口。

方案一：基于API网关聚合（最推荐，生产环境通用做法） #

如果你的微服务集群已经部署了Spring Cloud Gateway，直接在网关层加配置即可，没有网关的话新建一个轻量Spring Boot应用做网关入口也可以。

• 第一步：引入依赖
  根据你用的Spring Boot版本引入对应依赖，不要用已经停更3年以上的Springfox，兼容性问题极多，直接用维护活跃的springdoc-openapi即可：

<!-- Spring Boot 3.x 版本用这个依赖 -->
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webflux-ui</artifactId>
    <version>2.3.0</version>
</dependency>
<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-gateway</artifactId>
</dependency>

如果是Spring Boot 2.7.x版本，把上面springdoc依赖的版本换成1.7.0即可。

• 第二步：配置路由与文档映射
  在网关服务的application.yml中添加以下配置，按照你的实际服务地址替换对应内容：

server:
  port: 8080 # 统一入口端口
spring:
  cloud:
    gateway:
      routes:
        # 每个微服务对应一条路由规则，以下是用户服务示例
        - id: user-service
          uri: http://用户服务部署IP:端口 # 替换成你实际的服务地址
          predicates:
            - Path=/user-service/**
          filters:
            - StripPrefix=1
        # 剩余15个微服务参照上面的格式依次添加路由即可
springdoc:
  swagger-ui:
    path: /swagger-ui.html # 这就是你要的统一Swagger访问地址
    # 配置所有微服务的OpenAPI文档地址
    urls:
      - name: 用户服务
        url: /user-service/v3/api-docs
      - name: 订单服务
        url: /order-service/v3/api-docs
      # 剩余14个微服务依次添加，name填服务标识名，url填「网关路由前缀+原服务v3/api-docs路径」
  api-docs:
    path: /v3/api-docs

• 可选优化：如果你的所有微服务都已经接入Nacos/Eureka/Consul这类注册中心，不需要手动逐个配置urls，添加springdoc-openapi-cloud-discovery依赖后，开启springdoc.cloud.discovery.enabled=true配置，会自动从注册中心拉取所有健康服务的OpenAPI地址，后续新增微服务不需要修改聚合端配置。

配置完成后启动网关服务，直接访问http://网关IP:8080/swagger-ui.html，就能在同一个Swagger页面通过顶部下拉菜单切换所有16个微服务的接口文档，支持全局跨服务搜索接口。

方案二：无网关轻量聚合（适合测试/开发环境快速搭建） #

如果不想引入网关组件，直接新建一个普通Spring Boot应用作为聚合文档服务即可：

• 引入springdoc-openapi-starter-webmvc-ui依赖
• 在配置文件的springdoc.swagger-ui.urls下直接填写16个微服务的OpenAPI全路径地址，比如http://用户服务IP:端口/v3/api-docs
• 给所有16个微服务配置跨域规则，允许聚合文档服务的来源访问/v3/api-docs/**路径，避免浏览器跨域拦截
• 启动聚合服务后直接访问其swagger-ui地址即可

常见避坑点 #

• 不要用Springfox Swagger：该项目已经停止维护多年，和Spring Boot 2.6+版本的路径匹配规则存在大量兼容性问题，会出现文档加载失败、接口404等各种无解问题。
• 权限放行：如果你的服务有鉴权拦截器，记得给所有服务的/v3/api-docs/**、/swagger-ui/**、/swagger-resources/**路径放行，避免文档被拦截无法加载。
• 如果微服务配置了context-path，对应api-docs的路径要加上context-path前缀，不要直接抄默认路径。

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