SpringDoc OpenAPI分组配置：如何实现Swagger分组下拉展示？

问题场景 #

你通过Gradle引入SpringDoc-OpenAPI依赖：

implementation 'org.springdoc:springdoc-openapi-ui:1.7.0'

最初仅配置GroupedOpenApi时，Swagger UI显示No operations defined in spec!；添加OpenAPI全局配置后能看到所有端点，但需要实现分组下拉展示的效果。

正确配置方案 #

要实现分组展示，需要同时保留OpenAPI全局元数据配置和多个GroupedOpenApi分组规则配置，并且修正扫描路径的模糊配置，确保Spring能正确识别控制器。

完整配置类示例 #

@Configuration
public class SwaggerConfiguration {

    // 全局文档基础信息（必填，提供文档标题、版本等元数据）
    @Bean
    public OpenAPI springShopOpenAPI() {
        return new OpenAPI()
                .info(new Info().title("HoN Core Auth API")
                        .description("Authentication & authorization API")
                        .version("33")
                        .license(new License().name("(C) HoN")));
    }

    // 用户API分组
    @Bean
    public GroupedOpenApi userApi() {
        return GroupedOpenApi.builder()
                .group("user-api")
                .displayName("User API")
                // 指定用户控制器所在的具体包路径，避免使用"*"模糊扫描
                .packagesToScan("com.example.hon.auth.user")
                // 匹配所有以/users开头的接口路径
                .pathsToMatch("/users/**")
                .build();
    }

    // 管理员API分组
    @Bean
    public GroupedOpenApi adminApi() {
        return GroupedOpenApi.builder()
                .group("admin-api")
                .displayName("Admin API")
                .packagesToScan("com.example.hon.auth.admin")
                .pathsToMatch("/admin/**")
                .build();
    }
}

关键配置说明 #

• 同时配置两类Bean：OpenAPI负责全局文档的元数据展示，GroupedOpenApi定义每个分组的接口范围，缺一不可
• 精准扫描包路径：不要用packagesToScan("*")，这种模糊配置会导致Spring无法定位到控制器类，必须指定控制器所在的具体包
• 明确路径匹配规则：用**通配符匹配多级路径，比如/users/**会覆盖/users/login、/users/profile等所有子路径
• 多分组定义：每个分组对应一个GroupedOpenApi的Bean，Swagger UI顶部的下拉菜单会自动列出所有分组

效果验证 #

配置完成后，访问http://localhost:8080/swagger-ui/index.html，即可在页面顶部的下拉菜单中看到user-api、admin-api等分组选项，切换分组就能查看对应范围内的接口。

内容的提问来源于stack exchange，提问作者Peter Penzov