说实话最近一段时间我把手头几个老项目从 Spring Boot 2.x 往 3.x 上迁移最让我头疼的不是 JDK 17 的语法适配也不是 Actuator 端点的调整而是接口文档这块springfox 3.0.0 在 Spring Boot 3.x 里一启动就报 ClassNotFoundException那个报错直接把我看懵了。后来切到 springdoc-openapi才算是把 Spring Boot 3.x 时代的内置接口文档方案彻底跑通。如果你也正在折腾 Spring Boot 3.x或者刚新建了一个 3.x 项目想顺手集成 Swagger UI那这篇文章非常值得你花十分钟看完。我会从为什么必须换掉 springfox 讲起再到 springdoc-openapi 的依赖引入、基础配置、常用注解、分组方案、生产环境安全控制最后把我在踩坑过程中遇到的高频问题整理成一份排查手册保证你看完能直接照着抄。1. 为什么 Spring Boot 3.x 必须换掉 Springfox1.1 一句话说清楚从 javax 到 jakarta 的“大地震”Spring Boot 3.x 底层换用了 Spring Framework 6而 Spring Framework 6 的基准是 Jakarta EE 9最直观的变化是所有javax.servlet、javax.persistence之类的包名全部变成了jakarta.servlet、jakarta.persistence。这不仅仅是改个前缀那么简单它意味着所有依赖旧包名的第三方库在运行时根本找不到对应的类。Springfox 3.0.0 最后发版时间是 2020 年彼时 Spring Boot 2.x 还在用javax.servlet所以它的注解、自动配置类、静态资源映射全都基于旧命名空间。拿到 Spring Boot 3.x 环境下springfox 的springfox.documentation.spring.web.plugins.Docket里的 import 直接失败要么启动报NoClassDefFoundError要么 Bean 创建失败导致整个应用起不来。简单类比一下你之前的快递一直送到老地址现在整条街的门牌号全换了快递公司却没更新系统结果自然是一单都送不到。再一个现实问题是 springfox 项目基本处于停更状态社区大量 issue 无人处理Swagger 官方早就不再推荐 springfox。所以在 Spring Boot 3.x 的时代背景下换掉 springfox 不是“可选优化”而是迁移路上的必经操作。1.2 springdoc-openapi 凭什么能接住这波迁移springdoc-openapi 是一套基于 OpenAPI 3 规范的文档生成库它不是简单修修补补 springfox而是直接重新实现了一套基于 Spring 6 的文档扫描与聚合逻辑。它能自动扫描项目中的RestController、RequestMapping等注解把他们转换成 OpenAPI 3 格式的 JSON 数据再配合内置的 Swagger UI 页面渲染。最关键的是它天然兼容 Jakarta 命名空间所以在 Spring Boot 3.x 上没有任何水土不服的问题。日常写代码时你只需要在 Controller、实体对象上添加少量注解springdoc 就能把接口说明、参数含义、返回结构、状态码这些信息全部收集起来在线文档会跟随代码一起更新既不用像传统 Word 接口文档那样手动维护也不会出现“文档和代码对不上”的尴尬。它的部署形态也符合 Spring Boot 的习惯起步依赖 自动配置加一个 starter 就能用。默认的文档 JSON 地址是/v3/api-docs内置的 Swagger UI 地址是/swagger-ui.html也支持配置修改。从 Spring Boot 2.2 时代我就开始用 springdoc整体体验是越用越顺手尤其是在 OpenAPI 3 的 request body 描述、多分组管理、响应状态码展示这些方面信息量比 springfox 丰富太多。1.3 版本对照与选型建议选版本是个十分容易出问题的地方很多人上来就搜“springdoc-openapi 最新版本”结果引了个1.7.0在 Spring Boot 3.x 里依然报错。这里我直接给你一张我在本地环境中实测过的对照表Spring Boot 版本springdoc-openapi 版本Maven artifact2.x1.x如 1.7.0springdoc-openapi-ui3.0.x / 3.1.x2.2.0 及以上springdoc-openapi-starter-webmvc-ui3.2.x / 3.3.x2.3.0 及以上springdoc-openapi-starter-webmvc-ui3.4.x2.6.0 及以上springdoc-openapi-starter-webmvc-ui注意那个starter-webmvc-ui坑位它对应的是基于 Spring MVC 的 Web 项目。如果你的项目是 WebFlux 响应式模型则要换成springdoc-openapi-starter-webflux-ui。刚上手的人容易忽略 webmvc 和 webflux 的区别一旦用错会出现文档页面可访问但接口列表为空甚至直接依赖冲突的情况。我个人的建议是直接用 Maven 中央仓库搜索 artifactId再看项目版本号优先选 2.6.0 或更新的稳定版本它能同时兼容 Spring Boot 3.2、3.3 和 3.4。2. 五分钟完成 springdoc-openapi 基础接入2.1 引入依赖别用错 artifact 名接入的第一步就是加依赖。我在pom.xml里添加的是下面的内容dependency groupIdorg.springdoc/groupId artifactIdspringdoc-openapi-starter-webmvc-ui/artifactId version2.6.0/version /dependency如果你用的是 Gradle对应写法也很简单implementation org.springdoc:springdoc-openapi-starter-webmvc-ui:2.6.0这个 starter 会把 OpenAPI 解析、Swagger UI 静态资源、Spring MVC 自动映射这些全部打包进来。Spring Boot 项目加了之后无需再引入额外的 swagger-annotations 依赖里面已经带好了io.swagger.core.v3:swagger-annotations-jakarta。这个细节很重要因为很多人习惯性去加旧版io.swagger:swagger-annotations结果 import 出来的是io.swagger.annotations.Api与 springdoc 期望的io.swagger.v3.oas.annotations.*完全不是一回事后面我会展开说。2.2 启动后先看这两个入口UI 页面和 JSON 数据源依赖加完后正常启动 Spring Boot 项目你会发现控制台多了一些关于/v3/api-docs和/swagger-ui的日志。打开浏览器访问下面两个地址http://localhost:8080/swagger-ui/index.html这个就是内置的 Swagger UI 页面可以直接在页面上看到项目的所有接口列表还能展开每个接口查看参数说明甚至点击 Try it out 来发一次真实请求。http://localhost:8080/v3/api-docs这是一个原生的 JSON 数据源里面是一份标准的 OpenAPI 3 结构包含 openapi 版本号、info 信息、paths 路径、components 组件定义等。把这两个地址分开来理解会更清晰/v3/api-docs是整个文档的数据后端Swagger UI 只是一个渲染前端。UI 打开时浏览器会先去请求 api-docs 拿到 JSON再渲染成可交互的页面。这也导致一个常见现象你只配置了 UI 相关路径却忘了给 api-docs 做权限放行结果页面白屏因为底层 JSON 请求 403 了。这些问题后面我统一在排查部分讲。2.3 最小化配置与第一个可运行示例先给一个最简单的验证示例。假设我有这样一个小小的 ControllerRestController RequestMapping(/api/users) public class UserController { GetMapping(/{id}) public UserVO getUser(PathVariable Long id) { return new UserVO(id, 张三, zhangsanexample.com); } }在没有任何额外注解的情况下springdoc 会自动扫描到这个接口Swagger UI 里就会出现一个GET /api/users/{id}的条目。它虽然能展示路径和参数但描述信息是空的返回模型也可能只显示字段名。这就是继续说下面注解配置的意义所在把文档从“能看”做成“好用”。为了让文档看起来更完整第二步通常是配置 OpenAPI 的基本信息。Spring Boot 的配置文件里加一段springdoc: api-docs: enabled: true path: /v3/api-docs swagger-ui: enabled: true path: /swagger-ui.html try-it-out-enabled: true operations-sorter: method tags-sorter: alpha这里api-docs.path修改的是 JSON 数据源的地址swagger-ui.path修改的是 UI 访问路径。operations-sorter: method的意思是同一 Tag 下的接口按 HTTP 方法排序tags-sorter: alpha则让接口标签按字母排序。这些配置都是为了让自己和团队在本地调试、联调时看着更顺手。2.4 我把基础配置调成了这样有些项目 Controller 分散在不同模块甚至不同根包下springdoc 默认会扫描主类所在包及其子包如果接口不在这个包范围内文档就会漏掉。这种情况下需要显式告诉它扫描范围我常用的是在application.yml中配置springdoc: packages-to-scan: com.example.project.controller paths-to-match: /api/**,/internal/**packages-to-scan控制包扫描范围paths-to-match控制路径匹配范围两者是“且”的关系。比如我想把internal下面的管理接口排除在文档之外我可以只写/api/**这样内部接口即使被扫描到也不会展示。3. 注解实操把 API 文档从“能用”做到“好用”3.1 必学注解清单springdoc 的注解体系很清晰你不要每个都用但下面这几个必须掌握。我用一张表给你列清楚功能和应用位置注解作用位置用途TagController 类给一组接口起名字和描述用于 UI 里的标签分组OperationController 方法描述接口的用途、请求方式、响应说明Parameter方法参数、字段描述单个参数的含义、是否必填、示例值Schema参数对象、响应对象描述模型字段的类型、限制、示例影响 JSON 结构展示ApiResponse/ApiResponsesController 方法描述异常状态码和对应响应Hidden类、方法、字段隐藏接口或字段不让其出现在文档中这些注解统一来自包io.swagger.v3.oas.annotations。我见过不少同事从旧的 springfox 项目里复制代码import 却还留着io.swagger.annotations.Api一旦切到 springdoc 就疯狂报错因为这两个注解体系并不互通命名也不一样。3.2 一个把注解用全的 Controller 示例直接用一个相对完整的 Controller 展示一下实际效果。这个例子把路径参数、查询参数、请求体、响应模型全部都覆盖到了Tag(name 用户管理, description 用户增删改查相关接口) RestController RequestMapping(/api/users) public class UserController { Operation(summary 根据ID查询用户, description 查询成功后返回用户详细信息用户不存在时返回404) ApiResponses({ ApiResponse(responseCode 200, description 查询成功), ApiResponse(responseCode 404, description 用户不存在) }) GetMapping(/{id}) public UserVO getUser( Parameter(description 用户ID, example 1001) PathVariable Long id) { return userService.getById(id); } Operation(summary 分页查询用户列表, description 支持按关键字模糊查询) GetMapping public PageResultUserVO pageUsers( Parameter(description 页码从1开始, example 1) RequestParam(defaultValue 1) Integer pageNum, Parameter(description 每页数量最大100, example 10) RequestParam(defaultValue 10) Integer pageSize, Parameter(description 用户名关键字) RequestParam(required false) String keyword) { return userService.page(pageNum, pageSize, keyword); } Operation(summary 创建用户) PostMapping public UserVO createUser(RequestBody UserCreateDTO dto) { return userService.create(dto); } Hidden PostMapping(/internal/init) public void initData() { // 内部初始化接口不想暴露到文档 } }把这个 Controller 放进项目后启动Swagger UI 里能看到“用户管理”这个标签下的接口列表每一个接口都有完整的说明文字参数也带默认值和示例值。Hidden那个内部接口则不会出现在文档中非常适合用来处理管理员手动触发的任务接口。3.3 模型字段说明Schema 的正确姿势接口只描述参数还不够请求体和返回模型的字段说明同样直接影响前后端协作效率。Schema注解需要放在实体类字段上比如public class UserVO { Schema(description 用户ID, example 1001) private Long id; Schema(description 用户昵称, example 张三) private String name; Schema(description 邮箱, example zhangsanexample.com) private String email; }加了Schema之后OpenAPI JSON 中的components.schemas.UserVO结构会更完整Swagger UI 的 Model 区域里也能看到每个字段的中文说明和示例值。如果字段带有校验注解比如NotBlank、Emailspringdoc 也能自动识别并把约束信息带进文档这对前端做表单校验很有参考价值。需要说明的是Schema对required的判断有两个来源一个是Schema(requiredMode RequiredMode.REQUIRED)一个是字段上的NotNull、NotBlank等校验注解两者都能生效我一般倾向于后者因为代码同时承担了参数校验职责文档只是顺带产物。3.4 一个非常容易踩的 import 坑写 springdoc 注解时import千万别导错。我见过最多的问题就是把项目里遗留的 springfox 旧版本依赖一起打到新项目导致io.swagger.annotations.Api和io.swagger.v3.oas.annotations.Operation同时存在。IDE 不报错但编译期可能提示注解位置不合法或者运行后 Swagger UI 显示残缺。规范做法是引入 springdoc 之后就不要再引入io.springfox:springfox-swagger2和io.springfox:springfox-boot-starter同时确认pom.xml里没有遗留的springfox相关依赖哪怕是用 exclusions 排掉也是可以的。还有一种情况是把Parameter导成了io.swagger.v3.oas.annotations.responses.ApiResponse所在的包或者把Schemaimport 成javax.validation.constraints下的包。这种错误编译期不会立刻出现但运行时注解不生效位置不对就会导致 UI 上参数描述缺失。遇到这类诡异问题时我都是先看 import 行再排查注解包名这个顺序基本能解决八成“文档没生效”的问题。4. 分组、排序与多模块场景的处理4.1 用 GroupedOpenApi 把接口拆成多个组随着项目变大一个管理系统里常常同时包含用户端接口、管理端接口、第三方开放接口全部混在同一个 Swagger UI 页面里非常难用。springdoc 提供了GroupedOpenApi来按组拆分文档每个组对应独立的 UI 下拉选项和独立的 api-docs 地址。我一般这样定义分组配置Configuration public class OpenApiConfig { Bean public GroupedOpenApi publicApi() { return GroupedOpenApi.builder() .group(用户端接口) .pathsToMatch(/api/user/**) .packagesToScan(com.example.project.controller.user) .build(); } Bean public GroupedOpenApi adminApi() { return GroupedOpenApi.builder() .group(管理端接口) .pathsToMatch(/api/admin/**) .packagesToScan(com.example.project.controller.admin) .build(); } }配置完成后再看 Swagger UI右上角会出现一个下拉框可以切换“用户端接口”“管理端接口”两个文档集。每个分组对应独立的 JSON 地址比如/v3/api-docs/用户端接口。这种方案比给每个 Controller 单独加 Tag 的效果更彻底因为它是从源头切分数据源而不是简单在页面上打标签。4.2 多模块项目下的扫描策略多模块 Maven 工程里接口往往会放在各个业务子模块中但 springdoc 启动时只看主类所在包的扫描结果。如果你主类的包是com.example.project而某个模块的 Controller 在com.example.moduleA包下面扫描范围就对不上了。这时候常见的两种处理方式一种是在application.yml里用springdoc.packages-to-scan把多个根包都列进去用逗号分隔。另一种是把所有 Controller 收敛到一个独立的 Web 模块或者统一定义在一个公共的com.example.project.controller包下然后让每个业务模块往里注册 Controller。我实践经验是只要不是必须解耦的巨型项目优先收敛包结构配置上更省事如果是大型微服务建议每个微服务独立维护自己的文档不要试图跨服务聚合。另外多模块场景下还要当心一个坑某些模块的接口是通过 fiegn 内部调用的标注了FeignClient并不会被 springdoc 扫描。真正需要展示的只有RestController接口所以扫描不到某个模块时先确认它是 Controller 还是 Feign Client别花时间在错误方向上排错。4.3 文档界面的排序与展示优化Swagger UI 默认按 Controller 的内部加载顺序排列这个顺序在很多场景下并不符合业务直觉。通过 yml 配置可以做一些基础优化springdoc: swagger-ui: operations-sorter: method tags-sorter: alpha disable-swagger-default-url: trueoperations-sorter: method把同组接口按get/post/put/delete排序这样增删改查一目了然tags-sorter: alpha把标签做字母序处理。如果你想让某个 Controller 永远排在最上面可以在Tag(name AA_用户管理)这类名称前加一个字母前缀但这属于比较暴力的偏方适合要求严格的团队内部约定。5. 上线前的安全与生产配置5.1 按环境彻底关闭 API 文档文档功能虽好但生产环境默认暴露接口信息是件危险的事别人能通过 Swagger UI 看到你所有的接口路径、参数结构、字段定义这相当于把系统的内部结构直接交底。我的做法是在生产环境的配置文件中强制关闭文档springdoc: api-docs: enabled: false swagger-ui: enabled: false这样设置之后/v3/api-docs和/swagger-ui/**都会直接返回 404相关 JSON 数据也不会生成。我记得 springdoc 2.x 之后对 enabledfalse 的处理已经很彻底不会像早期版本那样只隐藏页面、JSON 仍然可访问。如果你用的是 springdoc 2.6.0这个配置完全够用。5.2 与 Spring Security 的放行配置如果项目里集成了 Spring Security不登录的情况下访问 Swagger UI 通常会被拦截。我本地调试时也要频繁处理这个权限问题。推荐的做法把文档相关路径单独放行方便开发和测试环境联调。一个常见的 Security 配置片段如下Bean public SecurityFilterChain filterChain(HttpSecurity http) throws Exception { http .authorizeHttpRequests(auth - auth .requestMatchers( /v3/api-docs/**, /swagger-ui/**, /swagger-ui.html ).permitAll() .anyRequest().authenticated() ); return http.build(); }这里的关键是/v3/api-docs/**和/swagger-ui/**都要放行因为 UI 页面会深入到/swagger-ui/index.html以及相关的静态资源路径。如果只放行了/swagger-ui.html依然可能因为静态资源 403 导致白屏。另外旧的 springfox 还有/swagger-resources/**和/webjars/**springdoc 2.x 下这些路径通常不需要额外放行它们已经内化到了/swagger-ui/**的映射中。5.3 内网环境用 Knife4j 提升体验Swagger UI 官方页面虽然功能完整但界面稍微朴素了一些而且半屏内容容易被请求区占据阅读体验一般。如果你在内网环境搭建接口文档平台可以考虑接入 Knife4j 提供更现代的前端样式。Knife4j 4.x 已经兼容 springdoc-openapi 和 Spring Boot 3.x引入依赖后访问/doc.html就能看到增强版界面。dependency groupIdcom.github.xiaoymin/groupId artifactIdknife4j-openapi3-jakarta-spring-boot-starter/artifactId version4.5.0/version /dependency需要注意的是 Knife4j 只是 UI 层面的增强底层解析仍然依赖 springdoc-openapi所以 springdoc 的配置项、分组、权限控制规则全部照常生效。我一般把 Knife4j 放在测试环境和内网环境中使用生产环境依然保持关闭状态。5.4 反向代理下的路径适配如果你的服务部署在 Nginx 等反向代理后面路径适配是经常出问题的环节。比如外部访问地址是https://api.example.com/user-service/swagger-ui/index.html而服务内部实际端口和上下文路径可能不同。springdoc 提供了springdoc.swagger-ui.config-url、springdoc.swagger-ui.url等配置项但最直接有效的方式是把代理后缀配置到server.forward-headers-strategyserver: forward-headers-strategy: framework开启后 Spring 会读取X-Forwarded-Prefix等代理头springdoc 生成的 api-docs URL 会自动加上前缀Swagger UI 里的接口请求地址就不会偏了。这个配置在容器化部署、网关转发时是必须的不然你看到的文档页面虽然打得开但“Try it out”发出去的请求全部 404。6. 高频问题排查实录6.1 UI 能打开但接口列表是空的这个问题的本质是 springdoc 的包扫描没覆盖到你的 Controller。我的排查路径是先访问/v3/api-docs看看 JSON 里paths节点是不是空对象。如果 paths 是空的基本可以确定是扫描问题如果 paths 里有接口但 UI 显示空白则更可能是静态资源或浏览器缓存问题。扫描问题多数发生在多模块项目或接口不在主类所在包下的情况。这时候在配置里显式写清楚springdoc.packages-to-scan或者springdoc.paths-to-match就能解决。还有一种可能是你的 Controller 没标RestController只用了Controllerspringdoc 默认不会把它当接口扫描进去。生产环境上遇到过几次代码迁移时从Controller改成RestController的动作被人忽略接口列表自然就少一截。6.2 启动报错、页面 404启动时报错通常集中在依赖冲突。最常见的场景是项目里残留了 springfox 相关依赖springfox 的自动配置类会在启动时加载并尝试处理旧版注解一旦与 springdoc 的 bean 重叠就会出现BeanCreationException。处理办法就是查pom.xml把所有io.springfox相关的依赖全部排除或删除。404 的问题要分两种情况如果你访问/swagger-ui.html出现 404先试试/swagger-ui/index.html。springdoc 2.x 的默认重定向行为在不同版本里略有差异/swagger-ui.html通常会重定向到/swagger-ui/index.html但如果你的 context-path 设置得比较特殊可能就需要修改springdoc.swagger-ui.path配置。如果你是访问/v3/api-docs出现 404则要检查springdoc.api-docs.enabled是不是被人改成了false。6.3 参数和字段不显示参数不显示最常见的原因是 import 包名导错了。打开你的 Controller 看 import 语句确认用的是io.swagger.v3.oas.annotations.Operation、io.swagger.v3.oas.annotations.Parameter、io.swagger.v3.oas.annotations.media.Schema这三件套。如果项目里还留着 springfox 的io.swagger.annotations.ApiOperation注解本身不会生效但 IDE 不报错很难一眼看出问题。字段不显示则要排查实体类上的Schema是否放对了位置以及访问修饰符是否 private。还有种情况是 Lombok 的Data与Schema同时使用时如果字段没有 getter/setterJSON 序列化没问题但 springdoc 基于字段解析时可能拿不到预期效果。我一般建议Schema放在字段上而不是 getter 方法上这样不管序列化走字段还是方法都能稳定生效。6.4 分页/排序参数不显示的配置很多项目用了 Spring Data 的Pageable、Sort作为接口参数springdoc 默认也能识别它们但会把参数展开成很怪异的名称比如page、size、sort并列展示有时候会因为泛型推断问题导致参数列表不完整。如果你想简化展示可以自定义参数对象比如定义一个PageQueryDTO把pageNum、pageSize、keyword收拢起来再配合ParameterObject注解springdoc 就能把它们的字段展开到 UI 中文档体验要友好很多。ParameterObject public class PageQuery { Schema(description 页码, example 1) private Integer pageNum 1; Schema(description 每页数量, example 10) private Integer pageSize 10; Schema(description 关键字) private String keyword; }这样 Controller 里直接写public Result page(PageQuery query)Swagger UI 就能精确展示三个参数而不是一长串光标怪异的分页参数。6.5 版本不兼容导致的行为怪异Spring Boot 版本升级到 3.4 之后springdoc 的低版本可能会出现操作异常、某些接口不展示等莫名其妙的问题。这通常与 Spring Framework 6.1 之后内部的 ant 路径匹配器调整有关。遇到这种情况优先升级 springdoc 到 2.6.0 以上不要停留在 2.2.0 这类旧版本上做无用排查。springdoc 的发布节奏跟 Spring Boot 是同步的新版本会提前适配好常见的框架变更所以保持依赖版本和 Boot 版本在同一代际很重要。最后再分享一个小技巧我习惯在本地写一个简单的 CI 脚本每次构建后自动把/v3/api-docs的 JSON 快照保存到项目仓库的docs/目录下。这样即使未来某个版本不小心把文档配置改崩了也能从 git 历史里快速对比出哪个接口的描述变了、哪个字段被删了联调阶段这个习惯帮我省了不少沟通成本。
说实话最近一段时间我把手头几个老项目从 Spring Boot 2.x 往 3.x 上迁移最让我头疼的不是 JDK 17 的语法适配也不是 Actuator 端点的调整而是接口文档这块springfox 3.0.0 在 Spring Boot 3.x 里一启动就报 ClassNotFoundException那个报错直接把我看懵了。后来切到 springdoc-openapi才算是把 Spring Boot 3.x 时代的内置接口文档方案彻底跑通。如果你也正在折腾 Spring Boot 3.x或者刚新建了一个 3.x 项目想顺手集成 Swagger UI那这篇文章非常值得你花十分钟看完。我会从为什么必须换掉 springfox 讲起再到 springdoc-openapi 的依赖引入、基础配置、常用注解、分组方案、生产环境安全控制最后把我在踩坑过程中遇到的高频问题整理成一份排查手册保证你看完能直接照着抄。1. 为什么 Spring Boot 3.x 必须换掉 Springfox1.1 一句话说清楚从 javax 到 jakarta 的“大地震”Spring Boot 3.x 底层换用了 Spring Framework 6而 Spring Framework 6 的基准是 Jakarta EE 9最直观的变化是所有javax.servlet、javax.persistence之类的包名全部变成了jakarta.servlet、jakarta.persistence。这不仅仅是改个前缀那么简单它意味着所有依赖旧包名的第三方库在运行时根本找不到对应的类。Springfox 3.0.0 最后发版时间是 2020 年彼时 Spring Boot 2.x 还在用javax.servlet所以它的注解、自动配置类、静态资源映射全都基于旧命名空间。拿到 Spring Boot 3.x 环境下springfox 的springfox.documentation.spring.web.plugins.Docket里的 import 直接失败要么启动报NoClassDefFoundError要么 Bean 创建失败导致整个应用起不来。简单类比一下你之前的快递一直送到老地址现在整条街的门牌号全换了快递公司却没更新系统结果自然是一单都送不到。再一个现实问题是 springfox 项目基本处于停更状态社区大量 issue 无人处理Swagger 官方早就不再推荐 springfox。所以在 Spring Boot 3.x 的时代背景下换掉 springfox 不是“可选优化”而是迁移路上的必经操作。1.2 springdoc-openapi 凭什么能接住这波迁移springdoc-openapi 是一套基于 OpenAPI 3 规范的文档生成库它不是简单修修补补 springfox而是直接重新实现了一套基于 Spring 6 的文档扫描与聚合逻辑。它能自动扫描项目中的RestController、RequestMapping等注解把他们转换成 OpenAPI 3 格式的 JSON 数据再配合内置的 Swagger UI 页面渲染。最关键的是它天然兼容 Jakarta 命名空间所以在 Spring Boot 3.x 上没有任何水土不服的问题。日常写代码时你只需要在 Controller、实体对象上添加少量注解springdoc 就能把接口说明、参数含义、返回结构、状态码这些信息全部收集起来在线文档会跟随代码一起更新既不用像传统 Word 接口文档那样手动维护也不会出现“文档和代码对不上”的尴尬。它的部署形态也符合 Spring Boot 的习惯起步依赖 自动配置加一个 starter 就能用。默认的文档 JSON 地址是/v3/api-docs内置的 Swagger UI 地址是/swagger-ui.html也支持配置修改。从 Spring Boot 2.2 时代我就开始用 springdoc整体体验是越用越顺手尤其是在 OpenAPI 3 的 request body 描述、多分组管理、响应状态码展示这些方面信息量比 springfox 丰富太多。1.3 版本对照与选型建议选版本是个十分容易出问题的地方很多人上来就搜“springdoc-openapi 最新版本”结果引了个1.7.0在 Spring Boot 3.x 里依然报错。这里我直接给你一张我在本地环境中实测过的对照表Spring Boot 版本springdoc-openapi 版本Maven artifact2.x1.x如 1.7.0springdoc-openapi-ui3.0.x / 3.1.x2.2.0 及以上springdoc-openapi-starter-webmvc-ui3.2.x / 3.3.x2.3.0 及以上springdoc-openapi-starter-webmvc-ui3.4.x2.6.0 及以上springdoc-openapi-starter-webmvc-ui注意那个starter-webmvc-ui坑位它对应的是基于 Spring MVC 的 Web 项目。如果你的项目是 WebFlux 响应式模型则要换成springdoc-openapi-starter-webflux-ui。刚上手的人容易忽略 webmvc 和 webflux 的区别一旦用错会出现文档页面可访问但接口列表为空甚至直接依赖冲突的情况。我个人的建议是直接用 Maven 中央仓库搜索 artifactId再看项目版本号优先选 2.6.0 或更新的稳定版本它能同时兼容 Spring Boot 3.2、3.3 和 3.4。2. 五分钟完成 springdoc-openapi 基础接入2.1 引入依赖别用错 artifact 名接入的第一步就是加依赖。我在pom.xml里添加的是下面的内容dependency groupIdorg.springdoc/groupId artifactIdspringdoc-openapi-starter-webmvc-ui/artifactId version2.6.0/version /dependency如果你用的是 Gradle对应写法也很简单implementation org.springdoc:springdoc-openapi-starter-webmvc-ui:2.6.0这个 starter 会把 OpenAPI 解析、Swagger UI 静态资源、Spring MVC 自动映射这些全部打包进来。Spring Boot 项目加了之后无需再引入额外的 swagger-annotations 依赖里面已经带好了io.swagger.core.v3:swagger-annotations-jakarta。这个细节很重要因为很多人习惯性去加旧版io.swagger:swagger-annotations结果 import 出来的是io.swagger.annotations.Api与 springdoc 期望的io.swagger.v3.oas.annotations.*完全不是一回事后面我会展开说。2.2 启动后先看这两个入口UI 页面和 JSON 数据源依赖加完后正常启动 Spring Boot 项目你会发现控制台多了一些关于/v3/api-docs和/swagger-ui的日志。打开浏览器访问下面两个地址http://localhost:8080/swagger-ui/index.html这个就是内置的 Swagger UI 页面可以直接在页面上看到项目的所有接口列表还能展开每个接口查看参数说明甚至点击 Try it out 来发一次真实请求。http://localhost:8080/v3/api-docs这是一个原生的 JSON 数据源里面是一份标准的 OpenAPI 3 结构包含 openapi 版本号、info 信息、paths 路径、components 组件定义等。把这两个地址分开来理解会更清晰/v3/api-docs是整个文档的数据后端Swagger UI 只是一个渲染前端。UI 打开时浏览器会先去请求 api-docs 拿到 JSON再渲染成可交互的页面。这也导致一个常见现象你只配置了 UI 相关路径却忘了给 api-docs 做权限放行结果页面白屏因为底层 JSON 请求 403 了。这些问题后面我统一在排查部分讲。2.3 最小化配置与第一个可运行示例先给一个最简单的验证示例。假设我有这样一个小小的 ControllerRestController RequestMapping(/api/users) public class UserController { GetMapping(/{id}) public UserVO getUser(PathVariable Long id) { return new UserVO(id, 张三, zhangsanexample.com); } }在没有任何额外注解的情况下springdoc 会自动扫描到这个接口Swagger UI 里就会出现一个GET /api/users/{id}的条目。它虽然能展示路径和参数但描述信息是空的返回模型也可能只显示字段名。这就是继续说下面注解配置的意义所在把文档从“能看”做成“好用”。为了让文档看起来更完整第二步通常是配置 OpenAPI 的基本信息。Spring Boot 的配置文件里加一段springdoc: api-docs: enabled: true path: /v3/api-docs swagger-ui: enabled: true path: /swagger-ui.html try-it-out-enabled: true operations-sorter: method tags-sorter: alpha这里api-docs.path修改的是 JSON 数据源的地址swagger-ui.path修改的是 UI 访问路径。operations-sorter: method的意思是同一 Tag 下的接口按 HTTP 方法排序tags-sorter: alpha则让接口标签按字母排序。这些配置都是为了让自己和团队在本地调试、联调时看着更顺手。2.4 我把基础配置调成了这样有些项目 Controller 分散在不同模块甚至不同根包下springdoc 默认会扫描主类所在包及其子包如果接口不在这个包范围内文档就会漏掉。这种情况下需要显式告诉它扫描范围我常用的是在application.yml中配置springdoc: packages-to-scan: com.example.project.controller paths-to-match: /api/**,/internal/**packages-to-scan控制包扫描范围paths-to-match控制路径匹配范围两者是“且”的关系。比如我想把internal下面的管理接口排除在文档之外我可以只写/api/**这样内部接口即使被扫描到也不会展示。3. 注解实操把 API 文档从“能用”做到“好用”3.1 必学注解清单springdoc 的注解体系很清晰你不要每个都用但下面这几个必须掌握。我用一张表给你列清楚功能和应用位置注解作用位置用途TagController 类给一组接口起名字和描述用于 UI 里的标签分组OperationController 方法描述接口的用途、请求方式、响应说明Parameter方法参数、字段描述单个参数的含义、是否必填、示例值Schema参数对象、响应对象描述模型字段的类型、限制、示例影响 JSON 结构展示ApiResponse/ApiResponsesController 方法描述异常状态码和对应响应Hidden类、方法、字段隐藏接口或字段不让其出现在文档中这些注解统一来自包io.swagger.v3.oas.annotations。我见过不少同事从旧的 springfox 项目里复制代码import 却还留着io.swagger.annotations.Api一旦切到 springdoc 就疯狂报错因为这两个注解体系并不互通命名也不一样。3.2 一个把注解用全的 Controller 示例直接用一个相对完整的 Controller 展示一下实际效果。这个例子把路径参数、查询参数、请求体、响应模型全部都覆盖到了Tag(name 用户管理, description 用户增删改查相关接口) RestController RequestMapping(/api/users) public class UserController { Operation(summary 根据ID查询用户, description 查询成功后返回用户详细信息用户不存在时返回404) ApiResponses({ ApiResponse(responseCode 200, description 查询成功), ApiResponse(responseCode 404, description 用户不存在) }) GetMapping(/{id}) public UserVO getUser( Parameter(description 用户ID, example 1001) PathVariable Long id) { return userService.getById(id); } Operation(summary 分页查询用户列表, description 支持按关键字模糊查询) GetMapping public PageResultUserVO pageUsers( Parameter(description 页码从1开始, example 1) RequestParam(defaultValue 1) Integer pageNum, Parameter(description 每页数量最大100, example 10) RequestParam(defaultValue 10) Integer pageSize, Parameter(description 用户名关键字) RequestParam(required false) String keyword) { return userService.page(pageNum, pageSize, keyword); } Operation(summary 创建用户) PostMapping public UserVO createUser(RequestBody UserCreateDTO dto) { return userService.create(dto); } Hidden PostMapping(/internal/init) public void initData() { // 内部初始化接口不想暴露到文档 } }把这个 Controller 放进项目后启动Swagger UI 里能看到“用户管理”这个标签下的接口列表每一个接口都有完整的说明文字参数也带默认值和示例值。Hidden那个内部接口则不会出现在文档中非常适合用来处理管理员手动触发的任务接口。3.3 模型字段说明Schema 的正确姿势接口只描述参数还不够请求体和返回模型的字段说明同样直接影响前后端协作效率。Schema注解需要放在实体类字段上比如public class UserVO { Schema(description 用户ID, example 1001) private Long id; Schema(description 用户昵称, example 张三) private String name; Schema(description 邮箱, example zhangsanexample.com) private String email; }加了Schema之后OpenAPI JSON 中的components.schemas.UserVO结构会更完整Swagger UI 的 Model 区域里也能看到每个字段的中文说明和示例值。如果字段带有校验注解比如NotBlank、Emailspringdoc 也能自动识别并把约束信息带进文档这对前端做表单校验很有参考价值。需要说明的是Schema对required的判断有两个来源一个是Schema(requiredMode RequiredMode.REQUIRED)一个是字段上的NotNull、NotBlank等校验注解两者都能生效我一般倾向于后者因为代码同时承担了参数校验职责文档只是顺带产物。3.4 一个非常容易踩的 import 坑写 springdoc 注解时import千万别导错。我见过最多的问题就是把项目里遗留的 springfox 旧版本依赖一起打到新项目导致io.swagger.annotations.Api和io.swagger.v3.oas.annotations.Operation同时存在。IDE 不报错但编译期可能提示注解位置不合法或者运行后 Swagger UI 显示残缺。规范做法是引入 springdoc 之后就不要再引入io.springfox:springfox-swagger2和io.springfox:springfox-boot-starter同时确认pom.xml里没有遗留的springfox相关依赖哪怕是用 exclusions 排掉也是可以的。还有一种情况是把Parameter导成了io.swagger.v3.oas.annotations.responses.ApiResponse所在的包或者把Schemaimport 成javax.validation.constraints下的包。这种错误编译期不会立刻出现但运行时注解不生效位置不对就会导致 UI 上参数描述缺失。遇到这类诡异问题时我都是先看 import 行再排查注解包名这个顺序基本能解决八成“文档没生效”的问题。4. 分组、排序与多模块场景的处理4.1 用 GroupedOpenApi 把接口拆成多个组随着项目变大一个管理系统里常常同时包含用户端接口、管理端接口、第三方开放接口全部混在同一个 Swagger UI 页面里非常难用。springdoc 提供了GroupedOpenApi来按组拆分文档每个组对应独立的 UI 下拉选项和独立的 api-docs 地址。我一般这样定义分组配置Configuration public class OpenApiConfig { Bean public GroupedOpenApi publicApi() { return GroupedOpenApi.builder() .group(用户端接口) .pathsToMatch(/api/user/**) .packagesToScan(com.example.project.controller.user) .build(); } Bean public GroupedOpenApi adminApi() { return GroupedOpenApi.builder() .group(管理端接口) .pathsToMatch(/api/admin/**) .packagesToScan(com.example.project.controller.admin) .build(); } }配置完成后再看 Swagger UI右上角会出现一个下拉框可以切换“用户端接口”“管理端接口”两个文档集。每个分组对应独立的 JSON 地址比如/v3/api-docs/用户端接口。这种方案比给每个 Controller 单独加 Tag 的效果更彻底因为它是从源头切分数据源而不是简单在页面上打标签。4.2 多模块项目下的扫描策略多模块 Maven 工程里接口往往会放在各个业务子模块中但 springdoc 启动时只看主类所在包的扫描结果。如果你主类的包是com.example.project而某个模块的 Controller 在com.example.moduleA包下面扫描范围就对不上了。这时候常见的两种处理方式一种是在application.yml里用springdoc.packages-to-scan把多个根包都列进去用逗号分隔。另一种是把所有 Controller 收敛到一个独立的 Web 模块或者统一定义在一个公共的com.example.project.controller包下然后让每个业务模块往里注册 Controller。我实践经验是只要不是必须解耦的巨型项目优先收敛包结构配置上更省事如果是大型微服务建议每个微服务独立维护自己的文档不要试图跨服务聚合。另外多模块场景下还要当心一个坑某些模块的接口是通过 fiegn 内部调用的标注了FeignClient并不会被 springdoc 扫描。真正需要展示的只有RestController接口所以扫描不到某个模块时先确认它是 Controller 还是 Feign Client别花时间在错误方向上排错。4.3 文档界面的排序与展示优化Swagger UI 默认按 Controller 的内部加载顺序排列这个顺序在很多场景下并不符合业务直觉。通过 yml 配置可以做一些基础优化springdoc: swagger-ui: operations-sorter: method tags-sorter: alpha disable-swagger-default-url: trueoperations-sorter: method把同组接口按get/post/put/delete排序这样增删改查一目了然tags-sorter: alpha把标签做字母序处理。如果你想让某个 Controller 永远排在最上面可以在Tag(name AA_用户管理)这类名称前加一个字母前缀但这属于比较暴力的偏方适合要求严格的团队内部约定。5. 上线前的安全与生产配置5.1 按环境彻底关闭 API 文档文档功能虽好但生产环境默认暴露接口信息是件危险的事别人能通过 Swagger UI 看到你所有的接口路径、参数结构、字段定义这相当于把系统的内部结构直接交底。我的做法是在生产环境的配置文件中强制关闭文档springdoc: api-docs: enabled: false swagger-ui: enabled: false这样设置之后/v3/api-docs和/swagger-ui/**都会直接返回 404相关 JSON 数据也不会生成。我记得 springdoc 2.x 之后对 enabledfalse 的处理已经很彻底不会像早期版本那样只隐藏页面、JSON 仍然可访问。如果你用的是 springdoc 2.6.0这个配置完全够用。5.2 与 Spring Security 的放行配置如果项目里集成了 Spring Security不登录的情况下访问 Swagger UI 通常会被拦截。我本地调试时也要频繁处理这个权限问题。推荐的做法把文档相关路径单独放行方便开发和测试环境联调。一个常见的 Security 配置片段如下Bean public SecurityFilterChain filterChain(HttpSecurity http) throws Exception { http .authorizeHttpRequests(auth - auth .requestMatchers( /v3/api-docs/**, /swagger-ui/**, /swagger-ui.html ).permitAll() .anyRequest().authenticated() ); return http.build(); }这里的关键是/v3/api-docs/**和/swagger-ui/**都要放行因为 UI 页面会深入到/swagger-ui/index.html以及相关的静态资源路径。如果只放行了/swagger-ui.html依然可能因为静态资源 403 导致白屏。另外旧的 springfox 还有/swagger-resources/**和/webjars/**springdoc 2.x 下这些路径通常不需要额外放行它们已经内化到了/swagger-ui/**的映射中。5.3 内网环境用 Knife4j 提升体验Swagger UI 官方页面虽然功能完整但界面稍微朴素了一些而且半屏内容容易被请求区占据阅读体验一般。如果你在内网环境搭建接口文档平台可以考虑接入 Knife4j 提供更现代的前端样式。Knife4j 4.x 已经兼容 springdoc-openapi 和 Spring Boot 3.x引入依赖后访问/doc.html就能看到增强版界面。dependency groupIdcom.github.xiaoymin/groupId artifactIdknife4j-openapi3-jakarta-spring-boot-starter/artifactId version4.5.0/version /dependency需要注意的是 Knife4j 只是 UI 层面的增强底层解析仍然依赖 springdoc-openapi所以 springdoc 的配置项、分组、权限控制规则全部照常生效。我一般把 Knife4j 放在测试环境和内网环境中使用生产环境依然保持关闭状态。5.4 反向代理下的路径适配如果你的服务部署在 Nginx 等反向代理后面路径适配是经常出问题的环节。比如外部访问地址是https://api.example.com/user-service/swagger-ui/index.html而服务内部实际端口和上下文路径可能不同。springdoc 提供了springdoc.swagger-ui.config-url、springdoc.swagger-ui.url等配置项但最直接有效的方式是把代理后缀配置到server.forward-headers-strategyserver: forward-headers-strategy: framework开启后 Spring 会读取X-Forwarded-Prefix等代理头springdoc 生成的 api-docs URL 会自动加上前缀Swagger UI 里的接口请求地址就不会偏了。这个配置在容器化部署、网关转发时是必须的不然你看到的文档页面虽然打得开但“Try it out”发出去的请求全部 404。6. 高频问题排查实录6.1 UI 能打开但接口列表是空的这个问题的本质是 springdoc 的包扫描没覆盖到你的 Controller。我的排查路径是先访问/v3/api-docs看看 JSON 里paths节点是不是空对象。如果 paths 是空的基本可以确定是扫描问题如果 paths 里有接口但 UI 显示空白则更可能是静态资源或浏览器缓存问题。扫描问题多数发生在多模块项目或接口不在主类所在包下的情况。这时候在配置里显式写清楚springdoc.packages-to-scan或者springdoc.paths-to-match就能解决。还有一种可能是你的 Controller 没标RestController只用了Controllerspringdoc 默认不会把它当接口扫描进去。生产环境上遇到过几次代码迁移时从Controller改成RestController的动作被人忽略接口列表自然就少一截。6.2 启动报错、页面 404启动时报错通常集中在依赖冲突。最常见的场景是项目里残留了 springfox 相关依赖springfox 的自动配置类会在启动时加载并尝试处理旧版注解一旦与 springdoc 的 bean 重叠就会出现BeanCreationException。处理办法就是查pom.xml把所有io.springfox相关的依赖全部排除或删除。404 的问题要分两种情况如果你访问/swagger-ui.html出现 404先试试/swagger-ui/index.html。springdoc 2.x 的默认重定向行为在不同版本里略有差异/swagger-ui.html通常会重定向到/swagger-ui/index.html但如果你的 context-path 设置得比较特殊可能就需要修改springdoc.swagger-ui.path配置。如果你是访问/v3/api-docs出现 404则要检查springdoc.api-docs.enabled是不是被人改成了false。6.3 参数和字段不显示参数不显示最常见的原因是 import 包名导错了。打开你的 Controller 看 import 语句确认用的是io.swagger.v3.oas.annotations.Operation、io.swagger.v3.oas.annotations.Parameter、io.swagger.v3.oas.annotations.media.Schema这三件套。如果项目里还留着 springfox 的io.swagger.annotations.ApiOperation注解本身不会生效但 IDE 不报错很难一眼看出问题。字段不显示则要排查实体类上的Schema是否放对了位置以及访问修饰符是否 private。还有种情况是 Lombok 的Data与Schema同时使用时如果字段没有 getter/setterJSON 序列化没问题但 springdoc 基于字段解析时可能拿不到预期效果。我一般建议Schema放在字段上而不是 getter 方法上这样不管序列化走字段还是方法都能稳定生效。6.4 分页/排序参数不显示的配置很多项目用了 Spring Data 的Pageable、Sort作为接口参数springdoc 默认也能识别它们但会把参数展开成很怪异的名称比如page、size、sort并列展示有时候会因为泛型推断问题导致参数列表不完整。如果你想简化展示可以自定义参数对象比如定义一个PageQueryDTO把pageNum、pageSize、keyword收拢起来再配合ParameterObject注解springdoc 就能把它们的字段展开到 UI 中文档体验要友好很多。ParameterObject public class PageQuery { Schema(description 页码, example 1) private Integer pageNum 1; Schema(description 每页数量, example 10) private Integer pageSize 10; Schema(description 关键字) private String keyword; }这样 Controller 里直接写public Result page(PageQuery query)Swagger UI 就能精确展示三个参数而不是一长串光标怪异的分页参数。6.5 版本不兼容导致的行为怪异Spring Boot 版本升级到 3.4 之后springdoc 的低版本可能会出现操作异常、某些接口不展示等莫名其妙的问题。这通常与 Spring Framework 6.1 之后内部的 ant 路径匹配器调整有关。遇到这种情况优先升级 springdoc 到 2.6.0 以上不要停留在 2.2.0 这类旧版本上做无用排查。springdoc 的发布节奏跟 Spring Boot 是同步的新版本会提前适配好常见的框架变更所以保持依赖版本和 Boot 版本在同一代际很重要。最后再分享一个小技巧我习惯在本地写一个简单的 CI 脚本每次构建后自动把/v3/api-docs的 JSON 快照保存到项目仓库的docs/目录下。这样即使未来某个版本不小心把文档配置改崩了也能从 git 历史里快速对比出哪个接口的描述变了、哪个字段被删了联调阶段这个习惯帮我省了不少沟通成本。
