Spring Cloud Gateway动态生成统一OpenAPI规范的实现方案咨询

当然可以通过Spring Cloud Gateway的路由映射来实现动态生成对外暴露接口的统一OpenAPI规范，下面分两种场景给你具体方案：

一、利用VMware Tanzu Spring Cloud Gateway原生功能 #

你提到的Tanzu版Spring Cloud Gateway确实自带OpenAPI version 3 auto-generated documentation功能，完全匹配你的需求：

• 只需启用相关依赖（比如spring-cloud-gateway-server-openapi），并在路由配置中通过metadata标记哪些路由是对外暴露的
• 网关会自动发现这些路由指向的微服务的OpenAPI文档（前提是微服务已暴露/v3/api-docs端点），然后仅聚合路由映射到的接口，自动生成统一的OpenAPI 3规范
• 最终可以通过网关的特定端点（比如/openapi）获取整合后的规范，也能直接访问Swagger UI页面查看对外接口

二、社区版Spring Cloud Gateway的自定义实现 #

如果用的是开源版Spring Cloud Gateway，也可以自己实现类似功能，核心思路是从路由映射反向过滤并聚合微服务的API文档：

• 步骤1：标记对外路由：在网关的路由配置中，给需要对外暴露的路由添加自定义metadata（比如"expose": "true"），用来区分对内和对外接口
• 步骤2：拉取微服务文档：网关通过定时任务或按需调用各微服务的/v3/api-docs端点，获取原始的OpenAPI文档
• 步骤3：过滤并转换路径：根据网关路由的路径映射规则，过滤掉未标记为对外的接口，同时将微服务的接口路径替换为网关的对外路径（比如把微服务的/user/info替换为网关的/api/user/info）
• 步骤4：聚合暴露规范：使用OpenAPI的Java SDK（比如io.swagger.core.v3:swagger-core）将过滤后的接口文档聚合为统一的OpenAPI对象，然后通过自定义端点（比如/gateway-api-docs）对外暴露

关键代码示例（核心逻辑） #

// 注入RouteLocator获取路由信息
@Autowired
private RouteLocator routeLocator;

// 聚合对外接口的OpenAPI文档
public OpenAPI aggregateExternalApis() {
    OpenAPI aggregatedOpenAPI = new OpenAPI()
            .info(new Info().title("对外统一API规范").version("1.0"));

    // 筛选标记为对外暴露的路由
    List<Route> externalRoutes = routeLocator.getRoutes()
            .filter(route -> Boolean.TRUE.equals(route.getMetadata().get("expose")))
            .collectList()
            .block();

    for (Route route : externalRoutes) {
        // 拉取对应微服务的OpenAPI文档
        String serviceDocs = restTemplate.getForObject(route.getUri() + "/v3/api-docs", String.class);
        OpenAPI serviceOpenAPI = Json.mapper().readValue(serviceDocs, OpenAPI.class);
        
        // 替换接口路径为网关对外路径并聚合
        serviceOpenAPI.getPaths().forEach((path, pathItem) -> {
            // 从路由断言中提取网关的对外路径前缀
            String gatewayPathPrefix = route.getPredicate().toString().split("=")[1].trim();
            String gatewayFullPath = gatewayPathPrefix + path;
            aggregatedOpenAPI.path(gatewayFullPath, pathItem);
        });
    }
    return aggregatedOpenAPI;
}

三、注意事项 #

• 确保微服务的/v3/api-docs端点仅在网关所在的内网可访问，避免直接暴露给外部
• 可以给文档拉取逻辑添加缓存，减少对微服务的频繁调用，提升性能
• 路由配置的metadata要严格维护，避免误将内部接口纳入对外规范

内容的提问来源于stack exchange，提问作者zashto