SpringDoc OpenAPI 中双星号路径端点被排除的问题解析

在SpringDoc OpenAPI 2.7.0版本中，开发者们发现了一个值得注意的行为变更：当API端点路径中包含双星号(/**)通配符时，这些端点将不会出现在生成的Swagger文档中。本文将深入分析这一问题的技术背景、影响范围以及解决方案。

问题背景

SpringDoc OpenAPI是一个流行的库，用于为Spring Boot应用自动生成OpenAPI/Swagger文档。在2.7.0版本之前，开发者可以自由地在控制器方法中使用双星号路径模式，例如：

@PostMapping("/**")
public String handleWildcardRequest() {
    // 处理逻辑
}

这样的端点会正常出现在生成的Swagger文档中。然而，自2.7.0版本起，这些端点突然从文档中消失了。

技术原因分析

问题的根源在于一个特定的提交，该提交原本旨在过滤掉Actuator端点中的双星号路径。Actuator是Spring Boot提供的生产级监控和管理端点，通常不需要包含在API文档中。

然而，这个过滤逻辑的实现方式过于宽泛，导致它不仅影响了Actuator端点，还意外地过滤掉了所有包含双星号的路径模式，包括开发者自定义的API端点。

影响范围

这一变更影响了以下场景：

1. 使用双星号作为路径匹配模式的REST端点
2. 需要为通配路径生成API文档的应用
3. 依赖于路径通配符实现特殊路由逻辑的系统

解决方案

SpringDoc团队已经修复了这个问题。修复方案是精确化过滤逻辑，确保只过滤Actuator相关的双星号路径，而不影响其他自定义端点。

对于开发者来说，解决方案包括：

1. 升级到包含修复的SpringDoc OpenAPI版本
2. 如果暂时无法升级，可以考虑显式定义路径而非使用通配符
3. 对于必须使用通配符的场景，可以自定义OpenAPI配置手动添加这些端点

最佳实践

为了避免类似问题，建议开发者在处理路径匹配时：

1. 尽量避免在API文档中暴露过于宽泛的通配路径
2. 如果必须使用通配符，考虑添加明确的路径前缀
3. 定期检查生成的OpenAPI文档是否完整包含所有预期端点
4. 在升级库版本后，进行全面的API文档验证

总结

SpringDoc OpenAPI对双星号路径的处理变更提醒我们，在框架设计中需要谨慎处理通配符逻辑。这个问题的解决也展示了开源社区快速响应和修复问题的能力。开发者应当关注这类变更日志，并在升级后验证关键功能的完整性，以确保API文档的准确性和完整性。