SpringDoc 这个工具其实已经火了挺长时间但每次看到群里还有人拿着 springfox 的旧配置往 Spring Boot 3 上塞然后被各种兼容性报错折磨我都想再写一遍这篇指南。SpringDoc 在国内被高频提及基本是和 OpenAPI 3、knife4j 绑定出现的比如 springboot4.1.0 springdoc openapi3 knife4j 这套组合现在已经成了不少新项目的接口文档标配。这篇文章就顺着这套组合往下聊从 SpringDoc 的基础用法、常用配置到和 knife4j 的整合再到实际项目中踩过的坑一次性讲清楚。1. 为什么现在还在写 SpringDoc 而不是 springfox很多老项目还在用 springfox也就是 Swagger 2 时代的方案。但如果你留意过 springfox 的 GitHub 仓库会发现它很久没有实质更新了对新版 Spring Boot 的适配基本处于停滞状态。我见过好几个项目在 Spring Boot 2.6 升 2.7 的时候就出现了路径匹配策略冲突到了 Spring Boot 3.x 更是直接不能用。而 SpringDoc 凭借对 OpenAPI 3 的原生支持、及时的版本跟进逐渐成了社区的主流选择。1.1 SpringDoc 和 springfox 的核心差异先摆结论新项目直接用 SpringDoc老项目也建议尽早迁移到 SpringDoc。迁移成本其实不高主要工作是把 Swagger 注解的包从 io.swagger.annotations 换成 io.swagger.v3.oas.annotations然后删掉 EnableSwagger2 这类注解再重新梳理一下配置类。从实现原理上看两者做的事情是一样的扫描 Controller 和 Model生成符合 OpenAPI 规范的 JSON 描述文件。但 SpringDoc 直接基于 Spring MVC 的 HandlerMapping 做扫描和装配而 springfox 是早年基于旧的 RequestMappingHandlerMapping 写的一套扫描逻辑。在新版 Spring 中HandlerMapping 的装配顺序和匹配策略变化很大springfox 经常出现接口漏扫、路径冲突、NPE 之类的问题。再说协议层面的差异。SpringDoc 原生支持 OpenAPI 3默认 JSON 地址是 /v3/api-docsUI 页面地址是 /swagger-ui.html 或 /swagger-ui/index.html。springfox 提供的是 /v2/api-docs也就是 Swagger 2.0 的协议。前端如果用 openapi-generator 或其它代码生成工具对接文档基于 OpenAPI 3 的 SpringDoc 明显更稳定生成的客户端代码也更规范。1.2 SpringDoc 的文档生成原理深入理解 SpringDoc 的工作机制对排查问题很有帮助。它不是单纯的运行时反射扫描而是在 Spring 容器启动过程中等所有 Bean 都装配完成后再触发一次文档模型的构建。它收集 RequestMapping 相关的处理信息从类上的 RestController、RequestMapping方法上的 GetMapping、PostMapping再到参数上的 RequestBody、PathVariable组合成 Operation 对象最后序列化成 OpenAPI 的 JSON。这个机制解释了为什么 SpringDoc 对接口定义方式有要求。如果你的接口方法返回类型定义得很随意比如直接返回 Map 或 Object生成的 schema 会是一团乱麻。反过来只要 Controller 方法写得规规矩矩参数和返回值都有明确的 DTO 类型SpringDoc 就能自动生成结构清晰的文档字段说明、类型、是否必填都给你标出来。1.3 什么场景下适合选 SpringDoc我判断一个项目适不适合用 SpringDoc主要看三点。第一项目用的是 Spring Boot 2.6 以上版本特别是 Spring Boot 3.x、4.x那不用犹豫直接 SpringDoc。第二团队有前后端分离的协作需求前端同学需要一份稳定、可自动化的接口文档。SpringDoc 的 OpenAPI 3 JSON 可以直接对接接口管理平台或者配合 knife4j 做线下协作。第三项目需要生成 SDK 或客户端代码。OpenAPI 3 的描述能力比 Swagger 2 强不少特别是对服务端响应模型、枚举、多态的处理代码生成成功率高很多。如果你只是要一个能看能调试的接口文档页面那 springfox 也能用但如果你想少折腾我建议直接用 SpringDoc。2. 快速集成 SpringDoc 到 Spring Boot 项目SpringDoc 的集成方式不复杂核心就是加依赖、写配置、加注解。但依赖版本是个容易踩坑的点尤其现在 Spring Boot 迭代很快不同大版本对应不同的 SpringDoc starter。2.1 引入依赖的正确姿势D:\Maven\repository 这种本地仓库不谈直接看 Maven 依赖写法。如果你是 Spring Boot 2.x 项目用这个坐标dependency groupIdorg.springdoc/groupId artifactIdspringdoc-openapi-ui/artifactId version1.7.0/version /dependency如果你是 Spring Boot 3.x 项目用的是 Jakarta EE依赖坐标变了dependency groupIdorg.springdoc/groupId artifactIdspringdoc-openapi-starter-webmvc-ui/artifactId version2.8.9/version /dependency如果你用的是 Spring Boot 4.x比如标题里提到的 springboot4.1.0那就需要用 2.8.x 或更新版本具体还是要以 Maven Central 上最新发布的版本为准。我建议集成之前先打开 Maven 仓库页面搜一下 org.springdoc确认最新版不要盲目复制老教程里的版本号。Gradle 用户也简单对应写法是implementation org.springdoc:springdoc-openapi-starter-webmvc-ui:2.8.9依赖加好之后SpringBoot 启动类什么都不用改直接启动项目访问 /swagger-ui.html 就能看到文档页面。这就是 SpringDoc 零配置启动的效果。2.2 核心配置文件详解虽然零配置能跑但生产环境肯定要加一堆自定义配置。我把常用的配置项整理成一份参考模板springdoc: api-docs: enabled: true path: /v3/api-docs swagger-ui: enabled: true path: /swagger-ui.html tags-sorter: alpha operations-sorter: alpha default-produces-media-type: application/json default-consumes-media-type: application/json几个关键配置说明一下springdoc.api-docs.pathAPI 文档 JSON 的访问路径默认 /v3/api-docs。有些公司网关层会过滤 /v3 前缀可以改成自定义路径。springdoc.swagger-ui.pathSwagger UI 页面路径默认 /swagger-ui.html。tags-sorter 和 operations-sorter都设为 alpha 后标签和接口会按字母排序文档页面看起来更规整尤其在接口数量多的时候很实用。default-produces-media-type 和 default-consumes-media-type统一设置默认的请求和响应格式避免每个接口单独写。还有一个经常被忽略的配置knife4j 增强开关knife4j: enable: true setting: language: zh_cn这个不是 SpringDoc 的配置但如果你按后面的方案集成了 knife4j就是必须加的。2.3 常用注解的用法和场景SpringDoc 的注解体系很直白对照你平时的 Controller 代码看就行。类级别用 Tag 描述一个模块name 和 description 是常用的两个属性Tag(name 用户模块, description 用户注册、登录、信息查询等接口) RestController RequestMapping(/api/users) public class UserController {方法级别用 Operation 描述单个接口Operation(summary 查询用户列表, description 分页查询用户支持关键字模糊匹配) GetMapping(/list) public ResultPageResultUserVO list(Parameter(description 页码) RequestParam Integer page) {参数上有几个注解经常搭配使用。Parameter 用来描述单个参数Schema 用在 DTO 字段上描述模型属性Schema(description 用户ID) private Long id; Schema(description 用户昵称, example 张三) private String nickname;还有几个隐藏接口、忽略字段的注解Hidden加在方法上整个接口不会出现在文档里。Operation(ignore true)也可以忽略某个操作。Schema(hidden true)加在字段上该字段不会出现在模型 schema 中。这里特别提醒一点如果你在 Controller 里直接返回 Result 这种统一响应体而我前面说的 DTO 模型没定义好SpringDoc 生成的 schema 可能会很复杂。建议把泛型里的 T 明确指定为具体的 VO、DTO这样文档描述就清晰很多。3. 从基础使用到 knife4j 整合实战配置方案光会启动还不够实际项目里往往需要接口分组、权限参数配置、UI 换皮等操作。这一节我把比较贴近生产的方案拿出来讲。3.1 多模块项目的接口分组配置项目比较大、接口多的时候所有 Controller 挤在一个文档里很难看。SpringDoc 提供按包路径分组的方式把不同模块的接口拆成独立的文档。springdoc: group-configs: - group: user packages-to-scan: com.example.controller.user - group: order packages-to-scan: com.example.controller.order - group: admin packages-to-scan: com.example.controller.admin配置好之后启动项目访问 /v3/api-docs/user、/v3/api-docs/order、/v3/api-docs/admin就能分别拿到各分组的 JSON 文档。Swagger UI 页面顶部也会多出一个下拉框可以切换分组。这里有个细节如果某个接口类不在 packages-to-scan 范围内但又想让它在文档里出现可以在配置里再加 paths-to-match 作为补充比如- group: common paths-to-match: /api/common/**分组配置和包扫描配置逻辑上是一样的就是一个包含关系理解了这点就能自由组合。3.2 全局认证参数配置现在后端接口基本都会用 JWT 或 Token 来做鉴权文档里不配置认证方式的话前端拿着文档去调试每个接口都要手动填 Token很麻烦。SpringDoc 提供了 OpenAPI 配置类的方式在项目里定义一个配置 BeanConfiguration public class OpenApiConfig { Bean public OpenAPI openAPI() { return new OpenAPI() .info(new Info() .title(XXX 项目接口文档) .description(这是项目 API 描述) .version(v1.0.0)) .addSecurityItem(new SecurityRequirement().addList(BearerAuth)) .components(new Components() .addSecuritySchemes(BearerAuth, new SecurityScheme() .type(SecurityScheme.Type.HTTP) .scheme(bearer) .bearerFormat(JWT))); } }这段代码的作用简单说就是定义了文档的基础信息和全局安全配置。前端在 Swagger UI 上点击 Authorize 按钮输入 Token 之后后续所有请求都会自动带上 Authorization 头。这类配置类的代码比较长建议单独放一个 config 包不要堆在启动类里。3.3 整合 knife4j 的具体步骤knife4j 是基于 SpringDoc 封装的一套 UI 增强方案提供更简洁的中文界面支持离线文档导出、接口调试等能力。和原始 Swagger UI 比起来我更喜欢 knife4j 的排版信息密度高字段说明一目了然。整合步骤很明确。第一步引入 knife4j 依赖替代原本的 springdoc starter。Spring Boot 3.x 项目用这个dependency groupIdcom.github.xiaoymin/groupId artifactIdknife4j-openapi3-jakarta-spring-boot-starter/artifactId version4.5.0/version /dependencySpring Boot 2.x 项目用dependency groupIdcom.github.xiaoymin/groupId artifactIdknife4j-openapi3-spring-boot-starter/artifactId version4.4.0/version /dependency注意整合 knife4j 之后就不需要再加 springdoc-openapi-starter-webmvc-ui 依赖了knife4j 这个 starter 已经包含了 springdoc。第二步在全局配置里关闭原生的 Swagger UI 路径避免两个 UI 冲突。其实不关也不影响访问但为了界面统一我会把 springdoc.swagger-ui.path 改成一个不用的路径比如 /swagger-ui-old。第三步启动项目访问 /doc.html这就是 knife4j 的文档页面。在 knife4j 4.x 版本里这个地址是固定的。页面左侧是接口模块列表右侧是接口详情和调试区整体体验比原生 Swagger UI 更适合中文团队。需要注意的是knife4j 毕竟依赖 springdoc 的底层解析所以 springdoc 的配置项在 knife4j 下依然生效。分组的配置、全局认证的配置通通可以复用。4. 常见问题与排查技巧实录实战中用 SpringDoc 遇到的坑不少是环境、版本、新旧注解混用引起的。我把典型问题整理成了速查表方便大家对照排查。问题现象可能原因解决方案启动报错 Failed to start bean documentationPluginsBootstrapperspringfox 和 springdoc 冲突或 springfox 不兼容新版本删除 springfox 依赖和 EnableSwagger2 注解清理 Swagger 2 相关配置/v3/api-docs 返回 404springdoc.api-docs.enabled 没开或路径被网关拦截确认配置 enabled: true改一个自定义路径绕过网关规则部分接口在文档里看不到Controller 没加 RestController或方法访问权限不是 public检查类注解确保方法有明确的 RequestMapping 注解接口模型字段缺失DTO 里字段没有 getter/setter或使用了 private 字段但类没有正常序列化检查模型类的可见性和序列化配置启动过程 NPE和 PathPattern 相关Spring Boot 2.6 默认使用 PathPattern 解析路径springfox 不兼容升级到 SpringDoc 2.x或者使用 spring.mvc.pathmatch.matching-strategyant-path-matcher 临时绕过knife4j 页面打不开依赖没替换干净没有引入 knife4j starter确认 maven 依赖中有 com.github.xiaoymin 相关坐标接口文档里中文乱码应用编码问题在 Spring Boot 配置里设置 server.servlet.encoding.force: true并确保源码文件是 UTF-84.1 版本冲突是最大的问题来源实测下来大多数 SpringDoc 相关报错都源于版本冲突。比如一个项目原本引了 springfox后来想要换 SpringDoc只加了新依赖、没删旧依赖启动时两个框架都在抢 HandlerMapping报错信息五花八门。另一个高频问题是 Spring Boot 版本和 SpringDoc 版本不对应。Spring Boot 2.x 项目错用 springdoc-openapi-starter-webmvc-ui 这个新坐标就会因为 Jakarta 和 javax 的差异运行不起来。反过来也一样Spring Boot 3.x 项目用了旧坐标启动时会报 ClassNotFoundException。排查思路很简单先看项目用的是 javax.servlet 还是 jakarta.servlet再用这个信息去选对应的 SpringDoc starter。Spring Boot 3.x 和 4.x 基本都是 Jakarta 体系选 springdoc-openapi-starter-webmvc-ui 就对了。4.2 接口模型 schema 不符预期有次朋友的项目已经集成了 SpringDoc接口能看到但参数结构完全不对比如应该是一个嵌套对象文档里却变成了一堆扁平字段。查了一下是他在参数里直接用了 HttpServletRequest然后方法签名上又加了 ParameterObject 注解导致 SpringDoc 把 HttpServletRequest 当成了业务参数去解析。这种情况最好在方法参数里明确用 DTO 对象接收参数再配合 ParameterObject 注解让 SpringDoc 正确展开字段。不要用 Map 接收也不要把 Servlet 相关对象暴露到接口签名里。另一个相关问题是枚举类在文档里显示异常。SpringDoc 默认会把枚举值列出来但如果枚举里定义了额外的 code 和 desc 字段生成的显示效果可能不是你要的。可以在枚举字段上用 Schema(allowableValues {A, B}) 手动限制可选项或者实现自定义的序列化器让文档展示更友好。4.3 生产环境关闭文档的几种方式文档在开发阶段是神器但上线之后往往需要关掉防止接口信息泄露。SpringDoc 支持用配置控制 API 文档和 UI 的启用状态springdoc: api-docs: enabled: false swagger-ui: enabled: false更适合的做法是通过 profile 控制。开发环境和测试环境打开生产环境关闭# application-prod.yml springdoc: api-docs: enabled: false swagger-ui: enabled: false如果你用的是 knife4j同样可以通过 knife4j.enable 控制增强功能配合 springdoc 的开关一起使用。重点提醒一下关闭 UI 不代表关闭 JSON 接口两个开关要一起关别留一个 /v3/api-docs 暴露在外面。4.4 启动越来越慢的排查方向接入 SpringDoc 之后如果项目启动时间明显增加一个原因就是接口数量太多文档解析阶段花费了不少时间。SpringDoc 在启动时会遍历所有 HandlerMapping 的方法对每个方法的参数、返回值做类型分析接口多、模型多的情况下确实有一定消耗。针对这个问题可以把分组配置做细不需要扫描的包在文档初始化时直接排除掉减少扫描范围。还可以检查是不是引入了非必要的依赖比如 springdoc-openapi-security 模块这个模块会把 Spring Security 的注解集成到文档中如果项目没有用 Spring Security就不需要引它。启动慢这个问题不好一概而论但大体思路是减少无谓扫描让 SpringDoc 只关注真正需要暴露的接口。4.5 实际项目中我常用的排查套路遇到 SpringDoc 相关问题时我会按照这样的顺序排查先看依赖关系树用 mvn dependency:tree 查一下是否存在多个版本的 springdoc 或 springfox 冲突。再看启动日志里有没有和 OpenAPI、DocumentationPluginsBootstrapper 相关的异常堆栈。没有异常但文档不对就去访问 /v3/api-docs 看原始 JSON对比接口路径是否和预期一致排除 UI 层的问题。最后再检查注解是否写全。优先怀疑漏了 Tag、Operation因为这类问题 UI 上表现不明显JSON 里却缺描述。实际项目里我还遇到过 swagger-ui 能打开但 knife4j 打不开的情况后来发现是端口冲突导致 /doc.html 被某个过滤器拦截了。这类问题不用硬猜直接看后端日志对照请求路径多半能快速定位。5. 一些小经验和补充建议SpringDoc 用了两三年最大的感受是它把接口文档这件事从“附加工作”变成了“顺手的事”。只要 Controller 和 DTO 写得规范文档质量自然有保证不需要额外维护一份 Markdown 接口说明。团队协作时前端直接打开 /doc.html 就能看字段和调试沟通成本降低很多。这里分享一个我后来才养成的习惯。每个接口的 Operation 描述我会尽量写成“前端可以直接照着调用”的样式比如不仅写“查询用户列表”还会补充分页参数的含义、默认值、排序规则以及返回数据中关键字段的业务含义。字段级别能用 Schema 描述的一定不偷懒description 和 example 都写上。时间久了这份文档就成了团队内部最及时的接口契约。再补充一点SpringDoc 和 knife4j 的版本更新都比较快大家在搜索解决方案时尽量带上具体版本号。不同大版本之间注解包名和配置项可能有一点调整复制网上的代码前先确认版本是否对口。这篇文章从 SpringDoc 的基础集成、配置项一直聊到了 knife4j 整合和常见问题排查。如果你是初次接触按第二部分的操作步骤走一遍就能跑起来如果你已经在用但希望文档更专业第三部分的分组和全局认证配置值得好好研究。文档工具说到底是为了让接口更清楚、协作更顺畅把握好这个目标具体用 SpringDoc 还是 knife4j反而不那么重要了。
