一、整体架构说明

在微服务架构中，通过网关聚合各服务的 Swagger 文档，实现统一查看和管理的需求。架构分为网关服务、微服务和前端三个角色：

网关服务
部署 Swagger 聚合组件（SwaggerResourceProvider + SwaggerResourceController），负责动态获取并聚合所有微服务的 API 文档。

微服务
每个微服务集成 Swagger，暴露自身的 API 文档接口（/v2/api-docs），供网关调用。

前端
通过访问网关提供的 Swagger UI 页面，实现一站式查看所有微服务的 API 文档。

---

二、核心依赖配置

1.网关服务依赖

引入 Swagger、Spring Cloud Gateway 及相关适配库（推荐使用 Knife4j 增强 UI）：

<!-- Spring Cloud Gateway 网关 -->
<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-gateway</artifactId>
</dependency>
<!-- Swagger 核心 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>
<!-- Swagger 与 Gateway 适配（解决 WebFlux 兼容性） -->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>3.0.3</version>
</dependency>
<!-- Swagger UI 原生依赖（官方 UI 界面）
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>3.0.0</version>
</dependency>
 -->

2.微服务依赖

每个微服务需引入 Swagger 依赖以暴露文档接口：

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

---

三、网关代码实现

1.Swagger 资源聚合器

动态从网关路由中获取微服务文档路径并聚合：

/**
 * 聚合所有微服务的 Swagger 资源
 */
@Primary
@Component("SwaggerResourceProvider")
@AllArgsConstructor
public class SwaggerResourceProvider implements SwaggerResourcesProvider {
    // 网关路由定位器（用于动态获取微服务路由）
    private final RouteLocator routeLocator;
    // 微服务 API 文档的默认路径（Swagger 暴露的文档接口）
    private static final String API_DOCS_PATH = "/v2/api-docs";

    @Override
    public List<SwaggerResource> get() {
        List<SwaggerResource> resources = new ArrayList<>();
        // 从网关路由中动态获取微服务名称和路径，聚合 Swagger 资源
        routeLocator.getRoutes().subscribe(route -> {
            String serviceId = route.getId();   // 路由 ID 通常为微服务名称（如 user-service）
            String path = route.getPredicate().toString();  // 路由路径
            // 构建微服务的 API 文档地址
            String apiDocsLocation = path.replace("/**", API_DOCS_PATH);
            // 添加资源（名称=服务名，地址=文档路径，版本=2.0）
            resources.add(buildSwaggerResource(serviceId, apiDocsLocation));
        });
        return resources;
    }
    // 构建 Swagger 资源对象
    private SwaggerResource buildSwaggerResource(String name, String location) {
        SwaggerResource resource = new SwaggerResource();
        resource.setName(name);  // 微服务名称
        resource.setLocation(location);   // 微服务的 API 文档地址
        resource.setSwaggerVersion("2.0");  // Swagger 版本
        return resource;
    }
}

2.Swagger 资源控制器

提供聚合后的资源列表给前端 UI：

/**
 * 向前端 Swagger UI 提供聚合后的资源列表
 */
@AllArgsConstructor
@RequestMapping("/swagger-resources")
@RestController("SwaggerResourceController")
@ConditionalOnProperty(prefix = "swagger", name = "enable", havingValue = "true")
public class SwaggerResourceController {
    // 注入资源聚合器
    private final SwaggerResourcesProvider swaggerResourcesProvider;
    /**
     * 提供所有微服务的 Swagger 资源列表（供 Swagger UI 加载）
     */
    @RequestMapping
    public List<SwaggerResource> getSwaggerResources() {
        return swaggerResourcesProvider.get();
    }
     /**
     * 提供 Swagger UI 配置（可选，使用默认配置即可）
     */
    @RequestMapping("/configuration/ui")
    public UiConfiguration getUiConfiguration() {
        return UiConfiguration.DEFAULT;
    }
}

3.Swagger 配置类

定义网关 Swagger 基本信息：

/**
 * 网关 Swagger 配置（定义 Swagger UI 基本信息）
 */
@Configuration
@ConditionalOnProperty(prefix = "swagger", name = "enable", havingValue = "true")
public class GatewaySwaggerConfig {

    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo()) // 配置文档标题、描述等信息
                .enable(true); // 启用 Swagger
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("微服务 API 文档聚合")
                .description("一站式查看所有微服务的接口文档")
                .version("1.0")
                .build();
    }
}

---

4.微服务配置

每个微服务需启用 Swagger 并暴露文档接口：

/**
 * 用户服务 Swagger 配置
 */
@Configuration
public class UserServiceSwaggerConfig {

    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                // 扫描当前服务的 Controller 包（根据实际包名修改）
                .apis(RequestHandlerSelectors.basePackage("com.example.user.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("用户服务 API 文档")
                .description("用户管理相关接口")
                .version("1.0")
                .build();
    }
}

---

四、网关路由配置示例

在 application.yml 中配置微服务路由：

# 网关配置（application.yml）
server:
  port: 8080 # 网关端口

spring:
  cloud:
    gateway:
      routes:
        # 用户服务路由（ID=服务名，断言=路径匹配，uri=服务地址）
        - id: user-service
          uri: lb://user-service # 微服务注册中心地址
          predicates:
            - Path=/user/** 

        # 订单服务路由（同理）
        - id: order-service
          uri: lb://order-service
          predicates:
            - Path=/order/**

# Swagger 开关配置
swagger:
  enable: true # 开发环境开启，生产环境关闭

---

访问方式

启动网关和微服务后，通过以下 URL 访问聚合文档：

• Swagger UI: http://网关地址/swagger-ui.html
• Knife4j 增强 UI: http://网关地址/doc.html