springdoc-openapi-ui v1.2.32无法识别Controller类全量接口映射
异常根因与处理方案
核心成因
springdoc-openapi-ui v1.2.32 存在接口扫描逻辑缺陷:当单个Controller类内存在2个及以上根路径完全相同的接口映射(如示例中/v1路径下的GET、POST接口)时,内部去重判断逻辑会错误触发同Controller下所有接口的路径归一化关联,将该类内其余不同路径的接口(如/v1/foo、/test)误判为非独立有效映射,直接过滤、不纳入文档生成范围。
该缺陷的触发特征与场景表现完全匹配:同Controller内同根路径的接口可正常生成文档,其余新增/不同路径的接口全部被忽略;将接口迁移到全新Controller类后,因不存在同根路径接口的触发条件,可被正常扫描生成文档。
用户提供的Swagger配置类未配置任何接口路径过滤规则,不存在主动屏蔽接口的逻辑,可排除配置导致的问题。
解决路径
- 优先升级依赖:将springdoc-openapi-ui版本升级到1.3.0及以上,该版本已修复该扫描去重逻辑bug,修正了错误将同Controller方法路径强制关联类级虚拟路径的判断逻辑。
- 版本受限无法升级的临时方案:给出现异常的Controller类补充类级
@RequestMapping注解(如@RequestMapping("/app")),打断内部错误的路径拼接关联,避免不同路径的接口被错误归并到虚拟分组下被过滤。 - 基础校验:确认该Controller类所有需要纳入文档的接口方法均使用public访问修饰符,springdoc默认不会扫描非public的接口方法。
内容的提问来源于stack exchange,提问作者Half_Duplex
相关产品推荐
相关产品推荐

