Spring Boot3+SpringDoc2集成GroupedOpenApi后Swagger UI异常

问题背景 #

多模块Maven应用从Spring Boot 2/javax迁移至Spring Boot 3/jakarta，同步升级SpringDoc从1.x到2.1.0。未配置GroupedOpenApi时Swagger UI显示正常，添加分组Bean后，UI提示“😱 Could not render nn, see the console.”和“No API definition provided.”，但/api-docs/c1等分组端点返回的YAML内容正确，应用本身运行正常。

当前依赖版本 #

spring-boot-starter-web:3.0.4

springdoc-openapi-starter-webmvc-ui:2.1.0
springdoc-openapi-starter-common:2.1.0
springdoc-openapi-starter-webmvc-api:2.1.0

swagger-ui:4.18.2
swagger-core-jakarta:2.2.9
swagger-annotations-jakarta:2.2.9
swagger-models-jakarta:2.2.9

配置信息 #

application.yml配置 #

# openapi documentation plus swagger
springdoc: 
  # openapi provides documentation in json format. Having it enabled is a requiment of swagger-ui
  api-docs:
    # URI. defaultValue=/v3/api-docs
    path: /api-docs
    # Enable / Disable springdoc-openapi enpoint
    enabled: true

  # swagger allows exercesicing the API from a browser
  swagger-ui:
    # URI. defaultValue=swagger-ui.html
    path: /docs
    # Enable / Disable the swagger-ui endpoint
    enabled: true
    # Sort endpoints alphabetically
    operationsSorter: method
    #Sort tags alphabetically
    tagsSorter: method

分组Bean代码 #

private GroupedOpenApi getGroupedOpenApi(String category) {
    GroupedOpenApi group = GroupedOpenApi.builder().group(category).pathsToMatch(String.format("/%s/**",category)).build();
    log.info("Creating documentation group {} : {}", category, group.toString());
    return group;
}

@Bean public GroupedOpenApi c1OpenApi() { return getGroupedOpenApi("c1"); }
@Bean public GroupedOpenApi c2OpenApi() { return getGroupedOpenApi("c2"); }
@Bean public GroupedOpenApi c3OpenApi() { return getGroupedOpenApi("c3"); }
@Bean public GroupedOpenApi c4OpenApi() { return getGroupedOpenApi("c4"); }

排查方向及解决方案 #

1. 移除独立Swagger UI依赖 #

SpringDoc 2.x的starter已内置适配版本的Swagger UI，单独引入swagger-ui:4.18.2会导致版本冲突。直接移除该依赖，仅保留SpringDoc的starter依赖即可。

2. 检查分组路径匹配逻辑 #

SpringDoc 2.x对pathsToMatch的匹配规则做了调整，可尝试显式指定包扫描范围，避免多模块下的路径匹配遗漏：

GroupedOpenApi.builder()
    .group(category)
    .pathsToMatch("/" + category + "/**")
    .packagesToScan("com.yourcompany." + category + ".controller")
    .build();

3. 显式配置默认全局分组 #

SpringDoc 2.x中配置分组后，默认全局API文档可能被隐式禁用，添加全局分组Bean确保Swagger UI能识别有效分组：

@Bean
public GroupedOpenApi defaultApi() {
    return GroupedOpenApi.builder()
        .group("default")
        .pathsToMatch("/**")
        .build();
}

4. 查看浏览器控制台错误详情 #

打开浏览器开发者工具（F12）查看控制台具体错误：

• 若提示404，检查springdoc.api-docs.path是否与分组路径正确映射
• 若提示解析错误，排查响应头编码或多模块下的API注解冲突问题

5. 确认Spring扫描范围 #

确保GroupedOpenApi配置Bean所在包被Spring正确扫描，同时分组对应的Controller模块也在OpenAPI的扫描范围内。

内容的提问来源于stack exchange，提问作者Jorge Moraleda