结论先行
多个 starter(如 passport 认证、file 文件)共存时,要让 Swagger UI 正确分组,做法只有两条:不注册全局 OpenAPI Bean、不设全局 springdoc.packages-to-scan / springdoc.paths-to-match;改用 GroupedOpenApi 给每个 starter 建一个分组,用 addOpenApiCustomizer 注入各自的标题,并让每个分组用 packagesToScan 只扫自己的包。
两个典型症状的根因:启动报 required a single bean, but 2 were found 是多个 starter 各自注册了全局 OpenAPI Bean;切到某个分组却仍显示另一个分组的接口,是全局 packages-to-scan 优先级高于分组配置、覆盖了分组自己的扫描范围。
问题背景
OpenAPI 是一套描述 REST 接口的标准规范(以前叫 Swagger):一段 JSON/YAML 文档描述「有哪些接口、路径、参数、返回值」,它本身只是一份数据、不参与业务逻辑。springdoc-openapi 是 Spring Boot 生态最常用的 OpenAPI 实现,会自动扫描 @RestController / @RequestMapping 等注解动态生成接口文档,并提供 Swagger UI 页面可视化查看与调试。
一句话:springdoc 把代码里的 Controller 自动变成网页版接口文档,Swagger UI 是看这份文档的界面。
| 地址 | 作用 |
|---|---|
/swagger-ui/index.html | Swagger UI 可视化界面 |
/v3/api-docs | 默认分组的 OpenAPI JSON |
/v3/api-docs/{group} | 某个分组的 OpenAPI JSON,如 /v3/api-docs/file |
/v3/api-docs/swagger-config | Swagger UI 下拉里有哪些分组 |
文件服务同时引入 passport-starter(认证)和 file-starter(文件)两个 starter 后,遇到了两个问题:
- 问题一:应用启动直接报错——springdoc 需要一个全局 OpenAPI 对象,却发现了两个(
passportOpenAPI与fileOpenAPI),报required a single bean, but 2 were found。 - 问题二:切换分组,接口却一模一样——解决启动报错后,Swagger UI 出现 file / passport 两个分组,但切到 passport 仍显示 file 的接口。
详细内容
根因分析:两个问题的真正原因
根因一:@ConditionalOnMissingBean 跨类失效
两个 starter 的自动配置都写了这样一段,试图「如果已经有 OpenAPI 我就不注册了」:
@Bean
@ConditionalOnMissingBean(OpenAPI.class)
public OpenAPI xxxOpenAPI(...) { ... }@ConditionalOnMissingBean 的语义是「容器里还没有这个类型的 Bean 时才注册」,但它在跨多个 @Configuration 类时存在时序问题:两个配置类在同一轮被解析,互相都看不到对方已经注册,于是两个 OpenAPI Bean 都注册了,最终冲突。
多个 starter 共存时,不要各自注册全局 OpenAPI Bean。全局的只能有一个,谁注册都可能和别的 starter 撞车。
根因二:springdoc 全局配置优先级高于分组配置
当时在 application.properties 里写了全局配置:
springdoc.packages-to-scan=com.sparrow.file
springdoc.paths-to-match=/**springdoc 源码 AbstractOpenApiResource 的逻辑是「全局优先,全局为空才回退用分组的」:
// springdoc 源码逻辑(简化)
List<String> packagesToScan = springDocConfigProperties.getPackagesToScan(); // 先取全局
if (packagesToScan.isEmpty()) { // 只有全局为空
packagesToScan = groupConfig.getPackagesToScan(); // 才用分组的
}于是全局的 com.sparrow.file 覆盖了 passport 分组自己的 com.sparrow.passport,导致所有分组都扫了 file 的包——这就是「切到 passport 还是 file 接口」的原因。
最终方案:分组策略
核心思路只有两条:
- 不注册全局 OpenAPI Bean,改用
GroupedOpenApi(分组)+addOpenApiCustomizer给每个分组注入自己的标题/描述。 - 不设全局
springdoc.packages-to-scan/springdoc.paths-to-match,让每个分组用自己的packagesToScan扫描自己的包。
把 Swagger UI 右上角的下拉框理解成「分组」:每个分组对应一个 GroupedOpenApi Bean,各自扫描不同的包、显示不同的标题,这样 file 和 passport 就能在同一个 Swagger UI 里互不干扰地共存。
完整案例:file + passport 两个 starter
下面以本项目实际代码为例,说明分组策略如何落地。
5.1 配置属性类 FileOpenApiProperties
用独立的 sparrow.file.openapi.* 前缀,避免和 springdoc 官方、passport 的配置冲突:
@ConfigurationProperties(prefix = "sparrow.file.openapi")
public class FileOpenApiProperties {
private boolean enabled = true;
private String title = "Sparrow File";
private String description = "Sparrow File";
private String version = "1.0";
private String group = "file";
private String packagesToScan = "com.sparrow.file";
// ... getter/setter、contact、license 略
}5.2 自动配置 FileAutoConfiguration(关键)
只注册「分组」,不注册全局 OpenAPI Bean,把标题等信息通过 customizer 挂到分组上:
@Bean
@ConditionalOnMissingBean(name = "fileGroup")
@ConditionalOnProperty(prefix = "sparrow.file.openapi", name = "enabled",
havingValue = "true", matchIfMissing = true)
public GroupedOpenApi fileGroup(FileOpenApiProperties properties) {
return GroupedOpenApi.builder()
.group(properties.getGroup()) // 分组名:file
.packagesToScan(properties.getPackagesToScan()) // 扫描包:com.sparrow.file
.addOpenApiCustomizer(openApi -> openApi.info(buildInfo(properties))) // 注入标题
.build();
}
private Info buildInfo(FileOpenApiProperties properties) {
Info info = new Info()
.title(properties.getTitle())
.description(properties.getDescription())
.version(properties.getVersion());
// contact / license 可选,这里略
return info;
}passport starter 的 PassportAutoConfiguration 同理,分组名为 passport、扫描 com.sparrow.passport。
5.3 配置文件 application.properties
只保留两个开关,不要写全局 packages-to-scan / paths-to-match:
# 正确写法:只开开关,其余交给分组自己配置
springdoc.api-docs.enabled=true
springdoc.swagger-ui.enabled=true
# 错误写法(会覆盖所有分组的扫描包,导致串包):
# springdoc.packages-to-scan=com.sparrow.file
# springdoc.paths-to-match=/**使用说明:如何新增一个分组
假设你新建了一个 xxx-starter,想让它也出现在 Swagger UI 下拉里,只需三步:
- 写一个
XxxOpenApiProperties,用独立前缀(如sparrow.xxx.openapi),定义title、group、packagesToScan。 - 在自动配置类里注册一个
GroupedOpenApiBean,用addOpenApiCustomizer注入 Info。 - 用
@ConditionalOnMissingBean(name = "xxxGroup")防止覆盖宿主的同名分组,用@ConditionalOnProperty支持开关关闭。
分组名(group)建议与 starter 名一致:file、passport、xxx。访问该分组的 JSON 文档地址就是 /v3/api-docs/{group}。
验证方法
重启应用后,依次验证:
# 1. 分组列表(应能看到 file、passport 两个 url)
curl http://localhost:9999/v3/api-docs/swagger-config
# 2. file 分组(应只有 file 的接口:upload.json / base64-upload.json 等)
curl http://localhost:9999/v3/api-docs/file
# 3. passport 分组(应只有 passport 的接口:登录 / 注册等)
curl http://localhost:9999/v3/api-docs/passport浏览器打开 http://localhost:9999/swagger-ui/index.html,右上角下拉切换分组,两个分组的标题和接口应该各自独立。
注意事项与踩坑清单
| 坑 | 现象 | 正确做法 |
|---|---|---|
多个 starter 各自注册全局 OpenAPI Bean | 启动报错 required a single bean, but 2 were found | 只注册 GroupedOpenApi,用 addOpenApiCustomizer 注入标题 |
设了全局 springdoc.packages-to-scan | 所有分组都显示同一个包的接口 | 删除全局配置,让分组各自 packagesToScan |
跨配置类用 @ConditionalOnMissingBean(类型) | 条件失效,出现重复 Bean | 分组用 @ConditionalOnMissingBean(name = "...")(按名字)更可靠 |
| Swagger UI 显示 "No API definition provided." | spec 接口没返回合法 JSON(常见于被认证拦截或分组为空) | 确认认证排除名单包含 /v3/api-docs、/swagger-ui/** |
如果项目有登录拦截,记得把 /v3/api-docs、/v3/api-docs/**、/swagger-ui/**、/swagger-ui.html 加到放行名单,否则 Swagger UI 会一直提示 "No API definition provided."(本项目已在 sparrow.authc.exclude-patterns 里放行)。
总结归纳
记住两条原则,就能让多个 starter 的接口文档在同一套 Swagger UI 里和平共处:不注册全局 OpenAPI Bean,不设全局 packages-to-scan / paths-to-match。
- 每个 starter 注册一个
GroupedOpenApi,分组名与 starter 一致(file / passport / xxx)。 - 用
addOpenApiCustomizer给分组注入标题与描述。 - 让每个分组用
packagesToScan只扫自己的包,删除全局扫描配置。 - 有登录拦截时,把
/v3/api-docs、/swagger-ui/**放进认证放行名单。
下一步:新增一个 starter 时,照「配置属性类 + 分组 Bean + 开关」三步走;验证时依次看 swagger-config 的分组列表、各分组的 api-docs 接口是否只含自己的包。
参考资料
- springdoc-openapi 官方文档
Spring Boot 集成、Swagger UI 与 /v3/api-docs 端点、GroupedOpenApi 分组的权威说明。
- OpenAPI Specification
OpenAPI 规范本体,接口描述格式(路径、参数、返回值)的权威定义。
- Swagger · OpenAPI 说明
Swagger 与 OpenAPI 的关系、Swagger UI 的用途。