Spring Cloud Gateway聚合Swagger3：构建安全可控的微服务API文档门户

1. 为什么需要API文档统一管理

在微服务架构中，随着业务模块不断拆分，一个中型系统可能包含几十个微服务。每个服务都有自己的API文档，开发人员要记住所有服务的文档地址几乎是不可能的。想象一下，每次调试接口都要在不同服务的Swagger页面之间来回切换，效率有多低。

我经历过一个真实项目，有15个微服务分散在不同服务器上。每次联调时，前端同事都要挨个问后端："用户服务的文档地址是什么？订单服务的Swagger能发我一下吗？"这种沟通成本高得吓人。后来我们引入Spring Cloud Gateway做文档聚合，所有服务的接口在一个页面就能查看，开发效率直接翻倍。

Swagger3（OpenAPI 3.0）是目前最流行的API文档规范，但原生Swagger UI只能展示单个服务的文档。通过网关聚合后，你可以：

• 在一个页面查看所有微服务的接口
• 统一管理文档访问权限
• 避免暴露内部服务地址
• 集中配置文档安全策略

2. 搭建基础聚合环境

2.1 依赖配置要点

首先确保你的Spring Cloud Gateway已经正常运行。我推荐使用Spring Boot 2.6.x + Spring Cloud 2021.x的组合，这是目前最稳定的版本。在网关服务的pom.xml中添加关键依赖：

xml复制<!-- Swagger聚合核心依赖 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

<!-- 网关需要webflux支持 -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-webflux</artifactId>
</dependency>

注意一个常见坑点：很多教程还在用老版本的springfox-swagger2，这个库已经不维护了。我们直接用springfox-boot-starter，它内置了对OpenAPI 3.0的支持。

2.2 核心配置类详解

创建Swagger资源提供者类，这是聚合功能的核心。我优化过的版本增加了服务发现自动注册功能：

java复制@Primary
@Component
@RequiredArgsConstructor
public class GatewaySwaggerProvider implements SwaggerResourcesProvider {
    
    private final RouteLocator routeLocator;
    private final DiscoveryClient discoveryClient;

    @Override
    public List<SwaggerResource> get() {
        Li