Springdoc中group-configs.display-name的作用及Groups与URLs关系的技术问询

开发者阿泽

2026-4-13

我正试着搞懂Springdoc里Groups和URLs之间的关联，举个实际配置的例子：

springdoc.swagger-ui.urls[0].url=${springdoc.swagger-ui.url}/myapp-api.yaml
springdoc.swagger-ui.urls[0].name=randomName
springdoc.group-configs[0].display-name=MyApp API 
springdoc.group-configs[0].group=myapp-api.yaml 
springdoc.group-configs[0].paths-to-match=${paths.to.match}

我一直没搞明白springdoc.group-configs[0].display-name这个属性的用处——它到底该显示在哪里？在Swagger UI里，好像是另一个属性在控制分组的显示名称。具体来说，UI里是通过SwaggerUrl对象来构建分组的displayName的，下面是AbstractSwaggerUiConfigProperties类里的一段代码，能清晰说明这个逻辑：

public SwaggerUrl(String group, String url, String displayName) {
            Objects.requireNonNull(group, GROUP_NAME_NOT_NULL);
            this.url = url;
            this.name = group;
            this.displayName = StringUtils.defaultIfEmpty(displayName, this.name);
        }

按照这个逻辑，最终在UI上显示的名称其实是URL配置里的name值（也就是springdoc.swagger-ui.urls[0].name对应的"randomName"，而不是我配置的"MyApp API"），除非给所有URL设置一个全局的displayName。但这种行为感觉很反常，因为全局的displayName是统一的，没办法给每个URL单独配置显示名称。

所以我想请教两个问题：