springdoc-openapi 集成说明

01两个依赖的本质区别

webmvc-ui 与 webflux-ui 并不是「UI 皮肤」的差异， 而是对应 Spring 生态里两套完全不同的 Web 技术栈：

02核心区别：阻塞 Servlet vs 非阻塞 Netty

这是理解「为什么必须选对」的关键。两个依赖背后是两种并发处理模型，性能特征与编程模型截然不同。

03自动装配条件（字节码证据）

两个核心配置类都带有 @ConditionalOnWebApplication 门控，且类型互斥：

SpringDocWebMvcConfiguration   → @ConditionalOnWebApplication(type = SERVLET)
SpringDocWebFluxConfiguration  → @ConditionalOnWebApplication(type = REACTIVE)

也就是说：应用是哪种栈，就只会有对应的那个配置类被激活，另一个直接不生效。

04本项目属于哪一类

证据链非常明确，本项目是 Servlet / MVC 栈：

• passport-starter/pom.xml 依赖 spring-boot-starter-web（而非 webflux）
• 控制器 import 的是 jakarta.servlet.http.HttpServletRequest 与 org.springframework.web.servlet.ModelAndView
• 全项目无 spring-boot-starter-webflux、无 Mono/Flux/RouterFunction

05用错的后果

因为 SpringDocWebFluxConfiguration 带 type=REACTIVE 条件， 在 Servlet 应用里根本不会被激活：

1. /v3/api-docs 不会被注册 → Swagger UI 页面能打开（webjar 静态资源在）， 但拉不到任何接口数据（空文档或 404）
2. 自定义的 OpenAPI Bean 仍会注册（它只是元数据，不依赖 webflux）， 但没有地方消费它来渲染文档

06依赖选择（正确配置）

把依赖从 webflux-ui 改为 webmvc-ui，版本保持 2.8.8：

<!-- passport-starter/pom.xml 与 bom/pom.xml -->
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
</dependency>

07API 配置说明

7.1 官方 springdoc 属性（写在宿主 application.properties）

# 是否暴露 /v3/api-docs
springdoc.api-docs.enabled=true
springdoc.api-docs.path=/v3/api-docs

# 是否开启 Swagger UI
springdoc.swagger-ui.enabled=true
springdoc.swagger-ui.path=/swagger-ui.html

# 只扫描指定包，避免扫到宿主业务包
springdoc.packages-to-scan=com.sparrow.passport
springdoc.paths-to-match=/**

7.2 自定义元信息属性（starter 提供的命名空间）

starter 通过 @ConfigurationProperties(prefix = "sparrow.passport.openapi") 暴露元信息，宿主项目可按需覆盖：

7.3 starter 隔离机制

• @Import + @EnablePassport：非隐式自动装配，宿主必须显式 @EnablePassport 才生效
• @ConditionalOnMissingBean(OpenAPI.class)：宿主自定义了 OpenAPI Bean 时，starter 自动让位
• @ConditionalOnProperty(...enabled)：可用 sparrow.passport.openapi.enabled=false 一键关闭
• 独立前缀 sparrow.passport.openapi.*：与官方 springdoc.* 及宿主自定义零冲突

08分组（GroupedOpenApi）—— 按应用隔离接口文档

springdoc 不会自动创建分组，需要通过 GroupedOpenApi Bean 显式声明。 对应关系：knife4j「分组」/ springfox Docket.groupName → springdoc GroupedOpenApi.group()。定义多个分组后， Swagger UI 右上角会出现下拉，按应用切换接口文档。

8.1 分组配置项

8.2 starter 内的分组 Bean

@Bean
@ConditionalOnMissingBean(name = "passportGroup")   // 按名覆盖，允许多分组共存
@ConditionalOnProperty(prefix = "sparrow.passport.openapi", name = "enabled", ...)
public GroupedOpenApi passportGroup(PassportOpenApiProperties properties) {
    return GroupedOpenApi.builder()
            .group(properties.getGroup())
            .packagesToScan(properties.getPackagesToScan())
            .build();
}

8.3 多应用共存示例

其它应用各定义一个不同 group 的分组，即可在同一下拉中隔离展示：

@Bean
public GroupedOpenApi fileGroup() {
    return GroupedOpenApi.builder()
            .group("file")
            .packagesToScan("com.sparrow.file")
            .build();
}