Springdoc OpenAPI 网关聚合文档配置优化实践

背景介绍

在微服务架构中，API网关作为统一入口，通常需要聚合各个微服务的Swagger文档。Springdoc OpenAPI作为Spring生态中优秀的API文档工具，提供了多种方式来实现这一需求。近期有开发者反馈在版本升级后，原有的GroupedOpenApi配置方式出现了异常行为。

问题本质分析

在Spring Boot 3.2.10 + Springdoc 2.5.0环境下，开发者可以通过GroupedOpenApi bean来配置网关文档聚合。但在升级到Spring Boot 3.3.4 + Springdoc 2.6.0后，该方式不再适用。这是因为：

1. GroupedOpenApi设计初衷是用于同一应用内的API分组
2. 网关场景需要的是跨服务的文档聚合，属于不同应用范畴
3. 新版本对文档聚合机制进行了优化调整

正确解决方案

Springdoc官方推荐使用SwaggerUiConfigProperties配合RouteDefinitionLocator来实现动态API分组。这种方案具有以下优势：

1. 完全动态化配置，无需硬编码
2. 自动适配网关路由变化
3. 支持服务发现机制
4. 配置简洁高效

核心实现代码如下：

@Autowired
public void configureSwaggerUrls(SwaggerUiConfigProperties swaggerUiConfigProperties, 
                               RouteDefinitionLocator locator) {
    swaggerUiConfigProperties.setUrls(
        locator.getRouteDefinitions()
            .map(route -> new SwaggerUrl(
                route.getId(), 
                "/v3/api-docs/" + route.getId(), 
                route.getId()))
            .toStream()
            .collect(Collectors.toSet()));
}

实现原理详解

该方案的工作原理可分为三个关键步骤：

1. 路由信息获取：通过RouteDefinitionLocator获取所有已注册的路由定义
2. URL转换：将每个路由转换为SwaggerUrl对象，其中包含：
   • 服务标识（route.getId()）
   • 文档访问路径（/v3/api-docs/{serviceId}）
   • 显示名称
3. UI配置注入：将生成的SwaggerUrl集合设置到SwaggerUiConfigProperties中

最佳实践建议

在实际项目中应用时，建议注意以下几点：

1. 统一文档路径前缀，保持规范
2. 考虑添加路由过滤逻辑，排除不需要文档展示的服务
3. 对于服务命名，建议采用有意义的标识符
4. 在网关层做好文档访问的权限控制
5. 考虑添加缓存机制提升性能

版本兼容性说明

该解决方案具有很好的版本适应性：

• Spring Boot 3.x全系列兼容
• Springdoc 2.5.0及以上版本支持
• 对Spring Cloud Gateway无特殊版本要求

总结

通过本文的分析可以看出，Springdoc OpenAPI在不同版本间的行为变化实际上是朝着更合理的设计方向演进。对于网关场景的文档聚合，采用动态URL配置的方式不仅解决了版本兼容问题，还提供了更灵活的扩展能力。开发者应当根据实际场景选择合适的实现方案，而非局限于特定的API使用方式。