麻雀窝 Sparrow Zoo

springdoc-openapi 集成说明:webmvc-ui 与 webflux-ui 如何选对

讲清 springdoc-openapi 的 webmvc-ui 与 webflux-ui 两组 starter 的本质区别、阻塞 Servlet 与非阻塞 Netty 的技术栈差异、互斥的自动装配条件,以及依赖选择、配置项与分组隔离的正确做法。

后端开发者,使用 Spring Boot Servlet/MVC 栈集成 springdoc-openapi(webmvc-ui,版本 2.8.8)发布于 更新于
选对 springdoc starter技术栈决定文档依赖webmvc-uiServlet 栈 · 阻塞Tomcat / Jettyjakarta.servletRequestMappingHandlerMappingwebflux-uiReactive 栈 · 非阻塞NettyServerWebExchangeRouterFunctionMono / Flux栈匹配 → 接口才被发现
阅读目录

结论先行

本项目是 Servlet / MVC 栈,必须使用 springdoc-openapi-starter-webmvc-ui,而不是当前的 springdoc-openapi-starter-webflux-ui(版本均为 2.8.8)。选错会导致 Swagger UI 页面能打开,但拉取不到任何接口数据(空文档或 404)。

两组 starter 的差异并不是「UI 皮肤」,而是对应 Spring 生态里两套完全不同的 Web 技术栈——阻塞的 Servlet 与非阻塞的 Reactive。两者的自动装配条件互斥:应用属于哪种栈,就只会激活对应的那个配置类,另一个直接不生效。

问题背景

给 Spring Boot 项目接入接口文档时,通常会引入 springdoc-openapi。它提供两部分能力:/v3/api-docs 生成 OpenAPI 规范(JSON),/swagger-ui.html 提供可交互的可视化调试界面。但 springdoc 针对不同 Web 技术栈提供了两组 starter,名字只差一个词,选错就会出现「UI 能打开、却没有任何接口」的困惑。

要理解这一点,先分清几个术语:

Servlet / MVC 栈
基于 spring-boot-starter-web,默认容器 Tomcat/Jetty,请求模型是阻塞的,用 HttpServletRequest、@RestController 编程。
Reactive / WebFlux 栈
基于 spring-boot-starter-webflux,默认容器 Netty,请求模型是非阻塞的,用 ServerWebExchange、Mono/Flux、RouterFunction 编程。
starter
Spring Boot 的依赖聚合包,一个 starter 会带入一组相关依赖并触发对应的自动装配。

springdoc 的两组 starter 正是为这两套栈分别准备的,只有匹配当前应用的技术栈,接口端点才能被正确扫描与暴露。

详细内容

两个依赖的本质区别

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

webmvc-ui 与 webflux-ui 对比
维度webmvc-uiwebflux-ui
目标技术栈Servlet 栈(阻塞式)Reactive 栈(响应式 / 非阻塞)
底层 Web 框架spring-boot-starter-web + Tomcat/Jettyspring-boot-starter-webflux + Netty
请求 / 响应类型jakarta.servlet.*(HttpServletRequest、ModelAndView)org.springframework.web.reactive.*(ServerWebExchange、Mono/Flux)
端点发现方式扫描 RequestMappingHandlerMapping 上的 @RestController扫描 RouterFunction Bean 及响应式 @RestController
文档端点注册OpenApiResource 以 MVC Controller 方式暴露 /v3/api-docs以 RouterFunction 方式暴露 /v3/api-docs

核心区别:阻塞 Servlet vs 非阻塞 Netty

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

阻塞 · Servlet + Tomcat(线程池模型)

  • 每个请求占用一个独立线程(Tomcat 默认约 200 线程)
  • 线程在等待 IO(数据库、远程调用)时会阻塞挂起,无法处理其他请求
  • 并发量受线程池大小限制,线程过多导致内存与上下文切换开销大
  • 编程模型:命令式、顺序执行,简单直观、易调试,生态成熟

非阻塞 · WebFlux + Netty(事件循环模型)

  • 基于 Reactor(Mono/Flux)+ Netty 事件循环
  • 少量线程(约等于 CPU 核数)即可承载大量并发连接
  • 等待 IO 时线程不阻塞,通过回调 / 事件驱动继续处理
  • 编程模型:响应式链式,高吞吐低占用,但复杂、难调试,生态相对少
为什么 springdoc 必须匹配

因为两套栈的「端点发现机制」不同:MVC 通过 RequestMappingHandlerMapping 拿 HandlerMethod,WebFlux 通过 RouterFunction 与响应式 Controller 拿路由。springdoc 内部用不同代码路径去扫描,选错栈就无法发现接口。

自动装配条件(字节码证据)

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

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

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

本项目属于哪一类

证据链非常明确,本项目是 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

用错的后果

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

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

依赖选择(正确配置)

把依赖从 webflux-ui 改为 webmvc-ui,版本保持 2.8.8:

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

API 配置说明

官方 springdoc 属性(写在宿主 application.properties)

springdoc 官方属性及默认值
属性默认值说明
springdoc.api-docs.enabledtrue是否暴露 /v3/api-docs
springdoc.api-docs.path/v3/api-docsapi-docs 端点路径
springdoc.swagger-ui.enabledtrue是否开启 Swagger UI
springdoc.swagger-ui.path/swagger-ui.html访问入口(会 302 到 /swagger-ui/index.html)
springdoc.packages-to-scan主类所在包只扫描指定包(隔离时建议显式声明)
springdoc.paths-to-match/**匹配的路径模式
code
# 是否暴露 /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=/**

自定义元信息属性(starter 提供的命名空间)

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

starter 自定义元信息属性及默认值
属性默认值说明
sparrow.passport.openapi.enabledtrue是否注册 starter 提供的 OpenAPI 元信息 Bean
sparrow.passport.openapi.titleSparrow Community文档标题
sparrow.passport.openapi.descriptionSparrow Community文档描述
sparrow.passport.openapi.version1.0版本号
sparrow.passport.openapi.contact.nameharry联系人
sparrow.passport.openapi.contact.urlhttp://www.sparrowzoo.com联系人主页
sparrow.passport.openapi.contact.emailzh_harry@163.com联系人邮箱

starter 隔离机制

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

现有 application.properties 中的 knife4j.enable / knife4j.production 是旧 knife4j 的遗留项,在 springdoc 下已失效,应替换为 springdoc.api-docs.enabled / springdoc.swagger-ui.enabled。

分组(GroupedOpenApi)—— 按应用隔离接口文档

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

分组配置项

分组相关属性及默认值
属性默认值说明
sparrow.passport.openapi.grouppassport分组名(下拉中显示)
sparrow.passport.openapi.packages-to-scancom.sparrow.passport该分组扫描的包,用于隔离

starter 内的分组 Bean

code
@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();
}

多应用共存示例

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

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

定义分组后,该分组的 spec 地址变为 /v3/api-docs/{group}(例如 /v3/api-docs/passport),需确保该路径在认证放行列表内(/v3/api-docs/** 已覆盖)。

总结归纳

一句话记住:应用是 Servlet / MVC 栈就用 webmvc-ui,是 Reactive / WebFlux 栈就用 webflux-ui,两组不可混用。

  • 两组 starter 的差别在技术栈与端点发现机制,不是 UI 皮肤;自动装配条件互斥。
  • 选错的典型症状:Swagger UI 能打开,但 /v3/api-docs 空文档或 404。
  • 本项目为 Servlet / MVC 栈,依赖应使用 springdoc-openapi-starter-webmvc-ui(2.8.8)。
  • 宿主用官方 springdoc.* 属性,starter 元信息走 sparrow.passport.openapi.*,前缀隔离互不冲突。
  • 按应用隔离文档用 GroupedOpenApi 分组,spec 地址变为 /v3/api-docs/{group},注意认证放行。

下一步:核对 pom 中的 starter 名称与当前技术栈一致;用 /v3/api-docs 验证接口是否被正确发现;将旧 knife4j 配置项替换为 springdoc 对应项。

参考资料

  1. springdoc-openapi 官方文档

    webmvc-ui 与 webflux-ui starter 的选型依据与快速上手说明。

  2. springdoc-openapi · Getting Started

    Maven/Gradle 依赖坐标与最小配置。

  3. springdoc-openapi · Properties

    springdoc.* 官方属性及默认值。