（九）Spring Cloud Alibaba 2023.x：微服务接口文档统一管理与聚合

前言

在上一篇文章中，我们提到微服务的 API 提供方案选择了 业务子服务高度自治、独立提供 API 接口 的模式，并通过 统一的网关服务 将请求转发到具体的子服务进行逻辑处理。这样虽然保证了子服务的独立性，但也带来了一个新的问题：项目中的接口分散在不同的子服务中，访问入口地址各不相同，给接口的统一管理与查看带来了不小的挑战。

本篇文章将围绕这一问题展开，介绍如何在分布式的微服务架构下，实现接口的集中管理与统一查看。

准备

主要依赖版本：

spring boot 3.3.5
spring cloud 2023.0.1
spirng cloud alibaba 2023.0.1.0
jdk 17

参看源码地址：

About 基于spring cloud alibaba生态快速构建微服务脚手架

实践

网关服务配置

1.pom.xml 引入 webflux 版本 springboc 依赖

xml 复制代码

<dependency>
  <groupId>org.springdoc</groupId>
  <artifactId>springdoc-openapi-starter-webflux-ui</artifactId>
  <version>2.6.0</version>
</dependency>

2.application-dev.yml 配置 springboc 多服务地址

yml 复制代码

springdoc:
  swagger-ui:
    urls:
      - name: cloud-producer
        url: /cloud-producer/v3/api-docs
      - name: cloud-consumer
        url: /cloud-consumer/v3/api-docs
      - name: 用户服务
        url: /cloud-user/v3/api-docs

3.application-dev.yml 配置springboc 文档路由

每个有 api 文档的服务都需要配置，可新增到接口路由地址后面

yml 复制代码

spring:
  cloud:
    gateway:
      discovery:
        locator:
          enabled: true  # 开启自动服务发现
      routes:
      #此处省略之前配置的服务路由配置
        - id: cloud-user-docs
          uri: lb://cloud-user
          predicates:
            - Path=/cloud-user/v3/api-docs
        - id: cloud-consumer-docs
          uri: lb://cloud-consumer
          predicates:
            - Path=/cloud-consumer/v3/api-docs
        - id: cloud-producer-docs
          uri: lb://cloud-producer
          predicates:
            - Path=/cloud-producer/v3/api-docs

4.网关过滤器AuthFilter.class 中放行 springboc 访问路径

java 复制代码

@Slf4j
@Component
public class AuthFilter implements GlobalFilter, Ordered {
    private static final List<String> EXCLUDE_PATH_LIST = List.of("/cloud-user/user/login");
    @Resource
    private RedisTemplate redisTemplate;
    private static final String SECRET_KEY = "expected-secret";
    @Override
    public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {
        ServerHttpRequest request = exchange.getRequest();
        String requestURI = request.getURI().getPath();
        // 白名单直接放行
        if (EXCLUDE_PATH_LIST.stream().anyMatch(requestURI::startsWith) ||
            requestURI.contains("/v3/api-docs") ||
            requestURI.contains("/doc.html")) {
            //...
        }
    }
}

业务服务配置

不需要单独在每个服务子服务中配置，因为我们前面提供了一个公共服务 cloud-common,每个业务子服务都引入了，所以只需要在公告服务中配置就能生效

1.pom.xml 引入 webmvc 版本 springboc 依赖

xml 复制代码

<dependency>
  <groupId>org.springdoc</groupId>
  <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
  <version>2.6.0</version>
</dependency>

2.新增 springdoc 接口文档配置类

统一配置每个服务接口访问前缀
添加全局请求头 token 属性字段

java 复制代码

@Configuration
public class OpenApiConfig {
    @Value("${spring.application.name}")
    private String serverName;
    private static final String SECURITY_SCHEME_NAME = "TokenAuth";
    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
        .servers(List.of(
            new Server().url("http://localhost:9090/" + serverName) // 这里写网关地址
        ))  // 配置全局 SecurityScheme
        .components(new Components()
                    .addSecuritySchemes(SECURITY_SCHEME_NAME,
                                        new SecurityScheme()
                                        .type(SecurityScheme.Type.APIKEY)
                                        .in(SecurityScheme.In.HEADER)
                                        .name(HttpHeaders.AUTHORIZATION) // 请求头token字段名
                                       )
                   )
        // 应用到所有接口
        .addSecurityItem(new SecurityRequirement().addList(SECURITY_SCHEME_NAME));
    }
}

注：http://localhost:9090网关地址根据具体环境进行调整

调试

1.启动并访问

启动网关服务：cloud-gateway

启动业务子服务：cloud-user

访问路径：http://localhost:9090/swagger-ui.html

2.请求登录接口

3.请求用户名称接口

将登录返回的 token 设置到文档全局 token 中

请求接口成功