总体思路与架构选择
- Swagger/OpenAPI 是用于设计、生成与展示 API 文档的工具,并非API 网关。在 Linux 环境中,常见做法是用专业的网关(如 Kong、Apigee)承载路由、鉴权、限流等能力,再把后端服务的 OpenAPI/Swagger 文档聚合到网关的开发者门户进行统一查看与调试。若仅需轻量体验,也可在网关前放置一个 Swagger UI 静态站点,通过反向代理统一访问。
方案一 轻量方式 Swagger UI 作为网关前端的统一文档入口
- 适用场景:快速演示、内部测试、无复杂网关策略需求。
- 核心步骤:
- 准备 OpenAPI/Swagger 文件(如 swagger.yaml/json)。
- 在 Linux 上部署 Swagger UI(Node 或 Docker 方式均可)。
- 使用 Nginx 反向代理,将网关域名下的 /api-docs 或 /docs 路由到 Swagger UI 服务,同时把业务请求代理到后端网关/服务。
- 访问形如 http://your-domain/docs 即可在统一入口查看与调试 API。
- 示例要点(Nginx 反向代理到 Swagger UI 服务):
- 说明:该方式便于“集中查看与调试”,但不等同于在网关内做路由/鉴权/限流等策略。
方案二 微服务网关整合 Swagger 聚合文档 Zuul 示例
- 适用场景:基于 Spring Cloud Zuul 的微服务体系,需要在网关层统一展示所有下游服务的 Swagger 文档。
- 核心步骤:
- 各微服务引入 Swagger 依赖(如 springfox-swagger2/springfox-swagger-ui),编写 Docket 配置,暴露 /v2/api-docs。
- 网关模块同样引入 Swagger 依赖,并提供一个 SwaggerResourcesProvider 实现,聚合下游服务的 /v2/api-docs 路径,例如:
@Component
@Primary
public class DocumentationConfig implements SwaggerResourcesProvider {
@Override
public List<SwaggerResource> get() {
List<SwaggerResource> resources = new ArrayList<>();
resources.add(swaggerResource("service-a", "/api-a/v2/api-docs", "2.0"));
resources.add(swaggerResource("service-b", "/api-b/v2/api-docs", "2.0"));
return resources;
}
private SwaggerResource swaggerResource(String name, String location, String version) {
SwaggerResource r = new SwaggerResource();
r.setName(name); r.setLocation(location); r.setSwaggerVersion(version);
return r;
}
}
- 在网关侧配置路由(如 /api-a/ → 服务 A,/api-b/ → 服务 B),保证网关能转发到下游的 /v2/api-docs。
- 访问网关的 /swagger-ui.html(或自定义路径),即可在页面中切换查看各服务的 API 文档。
- 说明:该方式实现了“在网关层聚合与切换查看”多服务文档,网关仍负责路由转发,文档聚合由 Swagger Resource Provider 完成。
方案三 与专业 API 网关协同 Kong Apigee 等
- 适用场景:生产级网关,需 鉴权、限流、熔断、观测 等能力,同时希望有统一的开发者门户。
- 核心步骤:
- 在 Kong/Apigee 上配置路由、插件(如 key-auth、rate-limiting、cors 等)。
- 将后端服务的 OpenAPI/Swagger 规范导入或同步到网关的开发者门户/文档中心,实现统一托管与在线调试。
- 在 Linux 上用 Nginx 或 Ingress 暴露网关域名,结合证书与访问控制,保证安全与高可用。
- 说明:此模式把“网关能力”与“文档门户”解耦,Swagger 负责规范与文档,网关负责运行时治理。
关键配置与运维要点
- 统一前缀与路由:为文档路径(如 /docs 或 /swagger-ui.html)与业务路径设置清晰前缀,避免冲突;网关路由需能正确转发到下游的 /v2/api-docs。
- 安全与访问控制:为文档入口与生产 API 分别配置 鉴权/白名单;启用 HTTPS/TLS,避免明文传输。
- 版本与一致性:多服务聚合时,确保各服务的 OpenAPI 版本与 分组清晰;必要时在网关侧做路径重写或版本前缀。
- 可观测性:为文档与网关接入 日志、指标与链路追踪,便于排查文档与后端不一致的问题。
- 持续交付:在 CI/CD 中自动校验与发布 OpenAPI 文档,保证文档与代码同步更新。