API Gateway Aggregation Guide¶
网关聚合多服务API文档指南¶
在微服务架构中,通常会有多个服务各自提供API文档。通过 CSAP Framework API Doc 的网关聚合功能,你可以在一个统一的界面中查看和切换所有服务的API文档。
📋 目录¶
使用场景¶
适用场景¶
- 微服务架构 - 多个微服务需要统一的文档入口
- API网关 - Spring Cloud Gateway、Kong、APISIX、Nginx 等
- 多租户系统 - 不同租户的API需要分开展示
- 多环境管理 - 开发、测试、生产环境的文档聚合
典型架构¶
┌─────────────────────────────────────────────────────────┐
│ API Gateway (网关层) │
│ │
│ 配置 resources: │
│ - 总后台API: /example-admin-api/csap/apidoc/parent │
│ - 门店API: /example-store-api/csap/apidoc/parent │
│ - 其他API: /example-other-api/csap/apidoc/parent │
│ │
└─────────────────────────────────────────────────────────┘
│ │ │
▼ ▼ ▼
┌────────┐ ┌────────┐ ┌────────┐
│ Admin │ │ Store │ │ Other │
│Service │ │Service │ │Service │
└────────┘ └────────┘ └────────┘
工作原理¶
1. 各微服务配置¶
每个微服务独立配置 CSAP API Doc,暴露自己的文档接口:
// Admin Service
@SpringBootApplication
@EnableApidoc("com.example.admin")
public class AdminServiceApplication {
// 暴露接口: /csap/apidoc/parent
}
// Store Service
@SpringBootApplication
@EnableApidoc("com.example.store")
public class StoreServiceApplication {
// 暴露接口: /csap/apidoc/parent
}
2. 网关层聚合¶
网关项目配置所有服务的文档地址:
csap:
apidoc:
resources:
- name: 总后台API
url: /example-admin-api/csap/apidoc/parent
- name: 门店API
url: /example-store-api/csap/apidoc/parent
3. 前端切换¶
用户在界面上通过下拉框选择不同的服务,动态加载对应的API文档。
快速开始¶
Step 1: 微服务配置¶
在每个微服务中添加依赖和配置:
<dependency>
<groupId>ai.csap.apidoc.boot</groupId>
<artifactId>csap-apidoc-boot-starter</artifactId>
<version>1.1.0</version>
</dependency>
@SpringBootApplication
@EnableApidoc("com.yourcompany.yourservice")
public class YourServiceApplication {
public static void main(String[] args) {
SpringApplication.run(YourServiceApplication.class, args);
}
}
Step 2: 网关项目配置¶
在网关项目的 application.yml 中配置:
server:
port: 8080
spring:
application:
name: api-gateway
csap:
apidoc:
resources:
- name: 总后台API
url: /example-admin-api/csap/apidoc/parent
version: v1.0
- name: 门店API
url: /example-store-api/csap/apidoc/parent
version: v1.0
- name: 其他API
url: /example-other-api/csap/apidoc/parent
version: v1.0
devtool:
enabled: true
Step 3: 配置路由(Spring Cloud Gateway示例)¶
spring:
cloud:
gateway:
routes:
- id: example-admin-api
uri: lb://example-admin-service
predicates:
- Path=/example-admin-api/**
- id: example-store-api
uri: lb://example-store-service
predicates:
- Path=/example-store-api/**
- id: example-other-api
uri: lb://example-other-service
predicates:
- Path=/example-other-api/**
Step 4: 访问文档¶
启动网关后,访问:http://localhost:8080/csap-api.html
在界面顶部的下拉框中选择不同的服务,即可查看对应的API文档。
配置详解¶
Resources 配置项¶
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
name |
String | 是 | 服务显示名称 | 总后台API |
url |
String | 是 | 文档接口地址 | /example-admin-api/csap/apidoc/parent |
version |
String | 否 | API版本号 | v1.0 |
完整配置示例¶
csap:
apidoc:
# 多服务聚合配置
resources:
- name: 总后台API
url: /example-admin-api/csap/apidoc/parent
version: v1.0
- name: 门店API
url: /example-store-api/csap/apidoc/parent
version: v1.0
- name: 其他API
url: /example-other-api/csap/apidoc/parent
version: v1.0
# 基本信息
api-info:
title: "网关聚合API文档"
description: "所有微服务的API文档聚合"
version: "1.0.0"
# 开发工具
devtool:
enabled: true
cache: true
前端界面¶
服务选择下拉框¶
在文档界面的顶部,会显示一个"选择服务"的下拉框,包含配置的所有服务:
┌─────────────────────────────────────────┐
│ 选择服务: [总后台API ▼] 分组 版本 │
│ - 总后台API │
│ - 门店API │
│ - 其他API │
└─────────────────────────────────────────┘
动态加载¶
当用户选择不同的服务时: 1. 前端向对应的 URL 发送请求 2. 加载该服务的完整API文档 3. 更新左侧的API列表树 4. 保留当前的视图状态
常见问题¶
Q1: 服务列表为空怎么办?¶
检查项:
1. 确认 resources 配置正确
2. 检查网关路由是否配置正确
3. 验证各微服务是否正常运行
4. 查看浏览器控制台是否有跨域错误
Q2: 切换服务没有反应?¶
解决方案: 1. 检查服务的文档接口是否可访问 2. 验证 URL 路径是否正确(通过网关的路径) 3. 查看网络请求是否成功返回
Q3: 如何在不同环境使用不同配置?¶
使用 Spring Profile:
# application-dev.yml
csap:
apidoc:
resources:
- name: 总后台API
url: http://localhost:8081/csap/apidoc/parent
# application-prod.yml
csap:
apidoc:
resources:
- name: 总后台API
url: /mq-admin-api/csap/apidoc/parent
Q4: 支持外部服务的文档吗?¶
支持!可以配置任何可访问的文档地址:
csap:
apidoc:
resources:
- name: 内部API
url: /example-internal-api/csap/apidoc/parent
- name: 外部API
url: https://external-service.com/csap/apidoc/parent
最佳实践¶
1. 命名规范¶
使用清晰的服务命名:
2. 版本管理¶
为不同版本的API使用不同的配置:
resources:
- name: 用户API v1
url: /user-api/v1/csap/apidoc/parent
version: v1.0
- name: 用户API v2
url: /user-api/v2/csap/apidoc/parent
version: v2.0
3. 环境隔离¶
使用环境变量:
resources:
- name: ${SERVICE_NAME:总后台API}
url: ${ADMIN_API_URL:/example-admin-api/csap/apidoc/parent}
version: ${API_VERSION:v1.0}
4. 监控和日志¶
记录服务切换日志,便于追踪:
5. 生产环境安全¶
在生产环境关闭 DevTools:
相关文档¶
示例项目¶
查看完整的网关聚合配置示例:
Happy Documenting! 🎉