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

目录

前言

准备

实践

网关服务配置

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

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

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

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

业务服务配置

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

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

调试

1.启动并访问

2.请求登录接口

3.请求用户名称接口

---

前言

在上一篇文章中，我们提到微服务的 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 依赖

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

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

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

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

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

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

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

@Slf4j
@Component
public class AuthFilter implements GlobalFilter, Ordered {private static final List<String> EXCLUDE_PATH_LIST = List.of("/cloud-user/user/login");@Resourceprivate RedisTemplate redisTemplate;private static final String SECRET_KEY = "expected-secret";@Overridepublic 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 依赖

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

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

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

@Configuration
public class OpenApiConfig {@Value("${spring.application.name}")private String serverName;private static final String SECURITY_SCHEME_NAME = "TokenAuth";@Beanpublic 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 中

请求接口成功