大家好，我最近在升级springdoc-openapi组件时碰到了一个非常棘手的问题，折腾了好一阵没找到根因，特意来请教下社区的朋友们。

问题背景与现象 #

我之前用的是springdoc-openapi-{common, ui, web-code,...}:1.6.13，配置了3个API组，启动时：

• SwaggerUiConfigProperties.urls、SwaggerUiConfigParameters.urls、SpringDocConfigProperties.groupConfigs都正常包含3个元素，和配置完全匹配。

但当我升级到springdoc-openapi-starter-{common, webmvc-api, webmvc-ui}:2.8.14后，出现了诡异的情况：

1. 应用启动时，三个配置对象还是各有3个元素，一切正常；
2. 但第一次访问http://localhost:8084/swagger-ui/index.html后，SpringDocConfigProperties.groupConfigs突然变成了6个元素——出现了半重复的组定义；
3. 这些半重复的组不是完全复制，而是URL和名称都有变化：
   • 原组：SwaggerUrl{url='v3/api-docs.yaml/myapp-api.yaml', name='MyApp API'}
   • 半重复组：SwaggerUrl{url='v3/api-docs/myapp-api.yaml', name='myapp-api.yaml'}
4. 最终SwaggerUiConfigParameters.urls也从3个变成6个，导致Swagger UI里每个组都显示两个条目：一个能正常加载API文档，另一个会提示Unable to render this definition。

关键差异分析 #

我对比了两个版本的源码，发现问题出在AbstractSwaggerWelcome的实现变化上：

• 在1.6.13版本中，init()方法里有一行swaggerUiConfigParameters.setUrls(swaggerUiConfig.cloneUrls());，会用SwaggerUiConfigProperties里的3个URL重置参数，所以即使groupConfigs有重复，最终UI还是只显示3个；
• 但2.8.14版本移除了这个重置逻辑，init()会直接基于groupConfigs的内容修改SwaggerUiConfigParameters，所以当groupConfigs变成6个后，UI参数里的URL也跟着变成6个。

已做的排查尝试 #

1. 我确认API的YAML文档本身是正常的：直接访问localhost:8084/v3/api-docs.yaml能拿到正确的定义，安全配置也没问题（新旧版本用的是同一套，访问没有权限问题）；
2. 我之前看到过类似的重复组问题，是用Set替代List解决的，但那是完全重复的对象，而我这里是半重复，这个方法不适用；
3. 我试过把配置里springdoc.swagger-ui.urls[X].url的.yaml去掉，但这样原有的正常组也无法加载API文档了，显然不可行。

我的配置片段 #

myapp.public=/rest/public/_myapp_/**
myapp.protected=/rest/protected/_myapp_/**
myapp.private=/rest/private/_myapp_/**

springdoc.swagger-ui.url=/v3/api-docs.yaml
springdoc.swagger-ui.disable-swagger-default-url=true
springdoc.swagger-ui.urlsPrimaryName=MyApp API
springdoc.swagger-ui.operationsSorter=[get, post, put, delete]
springdoc.swagger-ui.tagsSorter=alpha

# 第一组
springdoc.swagger-ui.urls[0].url=${springdoc.swagger-ui.url}/myapp-api.yaml
springdoc.swagger-ui.urls[0].name=MyApp API
springdoc.group-configs[0].display-name=MyApp API
springdoc.group-configs[0].group=myapp-api.yaml
springdoc.group-configs[0].paths-to-match=${myapp.public},${myapp.protected},${myapp.private}

# 第二组
springdoc.swagger-ui.urls[1].url=${springdoc.swagger-ui.url}/myapp-client-api.yaml
springdoc.swagger-ui.urls[1].name=MyApp Client API
springdoc.group-configs[1].display-name=MyApp Client API
springdoc.group-configs[1].group=myapp-client-api.yaml
springdoc.group-configs[1].paths-to-match=${myapp.public}

# 第三组
springdoc.swagger-ui.urls[2].url=/submoduleAPI/openapi.yaml
springdoc.swagger-ui.urls[2].name=Submodule API
springdoc.group-configs[2].group=/submoduleAPI/openapi.yaml
springdoc.group-configs[2].paths-to-match=/submoduleAPI/**

求助点 #

我现在完全搞不懂为什么访问Swagger UI后，groupConfigs会凭空多出3个半重复的组，而且升级到2.8.14后因为没有了旧版本的重置逻辑，导致这个问题暴露出来。想请教大家：

1. 这种半重复组是怎么产生的？是新版本的某个内部逻辑导致的吗？
2. 升级到2.8.14后，有没有办法配置或者通过代码调整，让Swagger UI只显示我配置的3个正确组，避免出现这些半重复的无效条目？

谢谢大家的帮忙！