Nacos+Gateway+Springdoc 集中管理API

Spring cloud Gateway 基于使用Netty作为内嵌服务器，而Netty基于WebFlux实现，因此如果想要springdoc的 Swagger UI 显示在网关微服务中，需要用到它的WebFlux UI库。

现有三个微服务项目，分别是gateway-service、shop-service、user-service，各依赖库版本如下：

依赖	版本
spring boot	2.6.1
spring cloud	2021.0.0
spring cloud alibaba	2021.1
springdoc openapi	1.5.13

由于只在gateway-service网关微服务上查看 Swagger UI 页面，因此另外两个业务微服务中只需要添加springdoc openapi的核心依赖库即可：

...
<dependency>
	<groupId>org.springdoc</groupId>
	<artifactId>springdoc-openapi-webmvc-core</artifactId>
	<version>${springdoc.version}</version>
</dependency>
...

而gateway-service中除了spring cloud gateway之外，还需要添加springdoc openapi webflux依赖：

...
<dependency>
	<groupId>org.springframework.cloud</groupId>
	<artifactId>spring-cloud-starter-gateway</artifactId>
</dependency>
<!-- spring cloud 2020之后的版本中不再自动引入Ribbon依赖，需要手动引入loadbalancer 否则会出现503错误 -->
<dependency>
	<groupId>org.springframework.cloud</groupId>
	<artifactId>spring-cloud-starter-loadbalancer</artifactId>
</dependency>
<dependency>
	<groupId>org.springdoc</groupId>
	<artifactId>springdoc-openapi-webflux-ui</artifactId>
	<version>${springdoc.version}</version>
</dependency>
...

在user-service和shop-service中进行服务注册、数据库连接等基础配置：

...
spring:
  application:
    name: user-service
  cloud:
    nacos:
      discovery:
        server-addr: localhost:8848
...

同时编写 Swagger 自定义配置类：

@Configuration
public class SpringDocConfig {
    @Bean
    public OpenAPI customOpenApi() {
        return new OpenAPI().info(new Info().title("User API")
                        .description("User API")
                        .version("v1.0.0")
                        .contact(new Contact()
                                .name("姓名")
                                .email("邮箱")));
    }
}

此时已经可以通过访问http://IP:微服务端口/v3/api-docs/来获取到openapi的 JSON 格式数据了。

接下来需要在gateway-service中获取到其他服务的名称，然后按服务名进行分组，可以参考 springdoc 微服务 demo 中的代码：

@Configuration
public class SpringDocConfig {
    @Bean
    @Lazy(false)
    public List<GroupedOpenApi> apis(SwaggerUiConfigParameters swaggerUiConfigParameters, RouteDefinitionLocator locator) {
        List<GroupedOpenApi> groups = new ArrayList<>();
        List<RouteDefinition> definitions = locator.getRouteDefinitions().collectList().block();

        definitions.stream().filter(routeDefinition -> routeDefinition.getId().matches(".*-service"))
                .forEach(routeDefinition -> {
                    String name = routeDefinition.getId().replaceAll("-service", "");
                    swaggerUiConfigParameters.addGroup(name);
                    GroupedOpenApi.builder().pathsToMatch("/" + name + "/**").group(name).build();
                });
        return groups;
    }

    @Bean
    public OpenAPI customOpenApi() {
        return new OpenAPI().info(new Info().title("springdoc gateway API")
                        .description("springdoc gateway API")
                        .version("v1.0.0")
                        .contact(new Contact()
                                .name("姓名")
                                .email("邮箱")));
    }
}

这个配置可以将一个服务下的 API 按照服务名分组，通过http://IP:网关端口/v3/api-docs/组名可以访问对应 API 数据。为了使请求路径更符合项目规范，将/v3/api-docs/组名改为/组名/v3/api-docs，需要对路由进行重写：

...
spring:
  application:
    name: gateway-service
  cloud:
    nacos:
      server-addr: localhost:8848
    gateway:
      discovery:
        locator:
          enabled: true
      routes:
        - id: user-route
          uri: lb://user-service
          predicates:
            - Path=/user/**
          filters:
            - RewritePath=/user/(?<path>.*),/$\{path}
        - id: shop-route
          uri: lb://shop-service
          predicates:
            - Path=/shop/**
          filters:
            - RewritePath=/shop/(?<path>.*),/$\{path}
        - id: openapi
          uri: http://localhost:${server.port}
          predicates:
            - Path=/v3/api-docs/**
          filters:
            - RewritePath=/v3/api-docs/(?<path>.*),/$\{path}/v3/api-docs

springdoc:
  swagger-ui:
    use-root-path: true
    urls:
      - name: user
        url: /v3/api-docs/user
      - name: shop
        url: /v3/api-docs/shop
...

至此，springdoc openapi在 Spring Cloud Gateway 中的聚合已经完成了，通过网关微服务的swagger-ui.html即可查看项目中其他微服务下的 API 接口。

另：如果在 Swagger UI 中使用 "Try it out" 功能出现跨域请求的错误，则需要额外进行一下配置

1. 在 Controller 上添加@CrossOrigin注解，例：

   @RestController
   @CrossOrigin
   public class UserController {
       ...
   }
   

2. 在网关微服务application.yml中添加配置：

   spring:
     cloud:
       gateway:
         globalcors:
           cors-configurations:
             '[/**]':
               allowedOrigins: "*"
               allowedMethods:
                 - GET
                 - POST
                 - PUT
                 - DELETE
                 - OPTIONS