Gateway+Swagger2配置聚合文档方式

下面是“Gateway+Swagger2配置聚合文档方式”的完整攻略，包含以下几个步骤：

1. 引入Swagger2依赖

在网关服务的pom.xml文件中添加Swagger2依赖：

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

2. 配置Swagger2基础bean

在网关服务的启动类中添加Swagger2配置Bean：

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build();
    }
}

3. 配置Swagger2聚合文档

在网关服务的application.yml中添加Swagger2聚合文档配置：

swagger:
  enabled: true
  title: Gateway+Swagger2聚合文档
  version: 1.0.0
  gatewayUrl: /gateway/
  apis:
    - name: service1
      url: http://localhost:8081/v2/api-docs
    - name: service2
      url: http://localhost:8082/v2/api-docs

swagger.enabled: 是否启用Swagger2聚合文档。
swagger.title: Swagger2聚合文档标题。
swagger.version: Swagger2聚合文档版本号。
swagger.gatewayUrl: 网关服务访问路径。
swagger.apis: 微服务API文档配置，包括微服务名称和API文档地址。

4. 构建Gateway聚合文档

在网关服务的启动类中添加Gateway聚合文档处理器：

@SpringBootApplication
@EnableDiscoveryClient
@EnableGateway
public class GatewayApplication {

    public static void main(String[] args) {
        SpringApplication.run(GatewayApplication.class, args);
    }

    @Bean
    public SwaggerHandler swaggerHandler(Environment environment) {
        return new SwaggerHandler(environment);
    }
}

在网关服务中创建SwaggerHandler类，并实现SwaggerResourcesProvider接口：

@Component
public class SwaggerHandler implements SwaggerResourcesProvider {

    private Environment environment;

    public SwaggerHandler(Environment environment) {
        this.environment = environment;
    }

    @Override
    public List<SwaggerResource> get() {
        List<SwaggerResource> resources = new ArrayList<>();

        String gatewayUrl = environment.getProperty("swagger.gatewayUrl");
        List<Map<String, String>> apis = (List<Map<String, String>>) environment.getProperty("swagger.apis");
        for (Map<String, String> api : apis) {
            String name = api.get("name");
            String url = api.get("url");

            SwaggerResource resource = new SwaggerResource();
            resource.setName(name);
            resource.setLocation(gatewayUrl + name + "/v2/api-docs");
            resource.setSwaggerVersion("2.0");
            resources.add(resource);
        }

        return resources;
    }
}

该处理器会根据配置的微服务API文档地址，通过网关访问每个微服务的Swagger2文档，并转换为聚合文档的形式。

示例1：聚合Spring Cloud微服务

例如，这里有一个网关服务名为gateway，同时还有两个Spring Cloud微服务名为service1和service2，它们的Swagger2文档均以RESTful API方式实现。我们需要将它们聚合为一个Swagger2文档，以便于开发者快速了解和测试每个服务的API。

在Gateway服务的扩展配置中，我们配置如下：

swagger:
  enabled: true
  title: Gateway+Swagger2聚合文档
  version: 1.0.0
  gatewayUrl: /gateway/
  apis:
    - name: service1
      url: http://localhost:8081/v2/api-docs
    - name: service2
      url: http://localhost:8082/v2/api-docs

在启动Gateway服务之后，我们可以通过访问Gateway服务的以下URL来查看聚合文档：

http://localhost:8080/gateway/swagger-ui.html

示例2：聚合非Spring Cloud微服务

例如，这里有一个网关服务名为gateway，同时还有两个非Spring Cloud微服务，它们的API文档由不同的Swagger2工具生成。我们需要将它们聚合为一个Swagger2文档，以便于开发者快速了解和测试每个服务的API。