Spring Boot 3 下用 Knife4j 4.x 替代 Swagger2 的完整落地指南

1. 为什么 Spring Boot 3 一升级Swagger2 就得靠边站先交代个背景我参与过一次内部项目升级从 Spring Boot 2.7 升到 3.x最先把人搞崩的不是业务代码而是 API 文档。pom 里还留着springfox-boot-starter 3.0.0的依赖应用启动直接报类加载冲突。一开始我以为是版本号写错了查了半天才发现根子不在这真正的坑是 Spring 6 彻底淘汰了javax.servlet这一套 API。Spring Boot 3 上来就是三个硬变化JDK 17 起步、Spring Framework 6、原来一堆javax.*的包全换成jakarta.*。而 Springfox 这个项目最后稳定版基本停留在 2020 年之后就没有实质性的跟进。它内部依赖的是老旧的javax.*和旧版 spring-plugin在 Spring Boot 3 上运行属于先天残疾。网上有人通过替换依赖、改编译参数强行让 Springfox 跑起来但 Spring 6 的 Servlet API 已经全部切到jakarta.servlet类库内部反射、组件扫描照样会踩雷。为了一个文档工具逼着整个工程吃补丁非常不值得。1.1 单是 javax 换 jakarta就够淘汰一批老库把javax.servlet改成jakarta.servlet表面上只是包名变了实际上对类库生态是一次大清洗。老库在编译时写死了javax.servlet的 import运行时如果找不到对应的类直接抛出NoClassDefFoundError。更隐蔽的是有些库不直接依赖 Servlet API而是通过反射去加载javax.servlet.Filter、javax.servlet.http.HttpServletRequest这类类名这类问题在编译期根本发现不了只有请求打过来才炸。Springfox 正好踩在两组问题上。它既要适应 Spring MVC 6 的 Handler 机制又要处理 Jakarta Servlet 环境的类加载而这两个改动都不是简单换个包名能糊弄过去的。就算你在 pom 里手动引入jakarta.servlet-api和对应的旧类桥接包Springfox 里的springfox.documentation.spring.web那套组件依然会扫描到不兼容的类导致启动时 Bean 创建失败。所以结论很直接Spring Boot 3 上别再碰 Swagger2 的老链路。1.2 Knife4j 4.x 掉头转向 OpenAPI 3是顺势而为Knife4j 在早期版本里一直依托 Springfox所以很多老项目用 Knife4j 2.x 配 Swagger2 配得很爽。但到了 Spring Boot 3 时代Springfox 自己已经不动了Knife4j 只能换底座。4.x 版本开始Knife4j 底层直接切换到 springdoc-openapi注解体系从io.swagger.annotations换成io.swagger.v3.oas.annotations文档规范也从 OpenAPI 2 升级到 OpenAPI 3。这意味着如果你打算在 Spring Boot 3 上用 Knife4j就不再是简单地把旧依赖换个坐标而是要接受一套新的注解命名习惯。比如类上的Api要改成Tag方法上的ApiOperation要改成Operation参数上的ApiParam要改成Parameter。虽然这些改动很机械但不少人就是卡在“只换了依赖、没换注解”这一步启动是正常了打开文档却什么都看不到原因就是 springdoc 根本不扫描旧版 Swagger2 注解。这篇文章后面会专门讲这套迁移清单。所以标题说“不带 Swagger2 玩”不是口号而是 Spring Boot 3 升级路上绕不开的选择。想继续用 Knife4j 的炫酷 UI想获得 OpenAPI 3 的完整能力就应该直接站到 Knife4j 4.x 的新链路上来。2. 版本血缘理清楚再动手填依赖整合 Knife4j 这类组件第一件事不是抄依赖而是先确认版本血缘。被 Spring Boot 3 坑过的人都知道光把 spring-boot-starter-parent 版本从 2.7 改成 3.2工程里一大堆 starter 都可能失效。Knife4j 也一样接口工程选错依赖坐标后面全是连锁反应。2.1 JDK 17 不是推荐是底线Spring Boot 3 官方要求 JDK 17 以上Knife4j 4.x 的 Jakarta 版本也按这个基线编译。如果你还在 JDK 8 或 JDK 11 上做测试编译阶段大概率会报UnsupportedClassVersionError或invalid target release这类错误。这一步没太多技巧就是老老实实把项目 JDK 版本切换到 17 或 21Maven 的java.version属性也同步改掉。我建议在 pom 里直接这样写避免 IDE 和命令行行为不一致properties java.version17/java.version spring-boot.version3.2.5/spring-boot.version /propertiesSpring Boot 3.2 之后的版本对springdoc-openapi的要求也更高了后面我会专门提这一点。2.2 Spring Boot 2.x 和 3.x 的 Knife4j starter 不是同一个Knife4j 4.x 为了适配两代生态准备了两个官方 starter项目环境依赖坐标Spring Boot 2.4 ~ 2.7knife4j-openapi3-spring-boot-starterSpring Boot 3.xknife4j-openapi3-jakarta-spring-boot-starter光看名字就知道Spring Boot 3 对应的版本专门带了 “jakarta” 标识。很多同学直接把老项目里的knife4j-openapi3-spring-boot-starter复制到 Spring Boot 3 工程里结果就是各种类冲突或文档页面白屏。Spring Boot 3 工程请认准这个坐标dependency groupIdcom.github.xiaoymin/groupId artifactIdknife4j-openapi3-jakarta-spring-boot-starter/artifactId version4.5.0/version /dependency另外要注意这个 starter 会传递依赖springdoc-openapi-starter-webmvc-ui所以一般情况下不需要你再手动引入 springdoc。如果你项目中已经有 springdoc尽量让版本跟着 Knife4j 传递进来的版本走不要自己固定一个老的 springdoc 1.x否则会出现接口扫描不到、OpenAPI 版本不匹配等问题。2.3 Spring Boot 3.0 / 3.1 / 3.2 之后版本选择有细微差别Knife4j 4.3.0 在 Spring Boot 3.0、3.1 上跑得挺稳但到了 Spring Boot 3.2 之后Spring Framework 对静态资源的处理逻辑有变化继续用太旧的 Knife4j 可能会遇到静态资源映射异常。我实际碰到过的情况是控制器和接口列表都正常但/doc.html打不开控制台报NoResourceFoundException最后排查下来是 Knife4j 版本停留在 4.3.0传递依赖的 springdoc 版本偏老升级到 4.4.0 之后问题消失。所以我的建议很简单Spring Boot 3.2 及以上版本Knife4j 直接上 4.4.0 或 4.5.0Spring Boot 3.0/3.1 用 4.3.0 问题也不大但为了减少以后升级的麻烦直接用 4.5.0 更省心。版本选对了后面 90% 的兼容问题都不会出现。3. 最小可运行工程两个配置文件加一段注解下面这套配置是我个人比较喜欢的最小结构。它不含任何多余插件就是把 Spring Boot 3 Web 工程和 Knife4j 串起来跑通后你再去加分组、认证这些增强功能。3.1 pom.xml 里真正必需的依赖除了基础的 spring-boot-starter-web核心就是 Knife4j 官方 starter。lombok 看个人习惯不影响 Knife4j。dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency dependency groupIdcom.github.xiaoymin/groupId artifactIdknife4j-openapi3-jakarta-spring-boot-starter/artifactId version4.5.0/version /dependency dependency groupIdorg.projectlombok/groupId artifactIdlombok/artifactId optionaltrue/optional /dependency这里要强调一个容易踩的坑如果工程里还有残留的springfox-boot-starter最好用 Maven 依赖树确认后移除。两个文档组件一起存在时io.swagger.annotations和io.swagger.v3.oas.annotations的类名非常相似但包不同IDE 里可能看不出大问题实际运行时注解扫描结果会一团糟。我在合作项目里见过 pom 里同时引了 Springfox 和 Knife4j结果文档页面能打开但所有接口都被识别成 “default”分组和描述全部丢失。查了半天就是依赖冲突。3.2 application.yml 的关键配置Knife4j 4.x 的配置项其实不多下面是常用的一段springdoc: packages-to-scan: com.example.demo.controller paths-to-match: /** api-docs: enabled: true path: /v3/api-docs swagger-ui: path: /swagger-ui.html knife4j: enable: true setting: language: zh_cnspringdoc.packages-to-scan用于告诉 springdoc 扫描哪个包下面的 Controller默认会从启动类所在包往下扫。如果你的 Controller 不在启动类包路径下就一定要显式写出来不然后面打开文档会发现接口列表是空的。这里的坑非常多下一节我会专门展开。knife4j.enable负责开启 Knife4j 的增强功能setting.language则让 UI 显示中文。这两个配置对最终体验影响很大建议保留。3.3 OpenAPI 信息配置类接下来写一个配置类主要目的是设置文档标题、描述、版本号。有人嫌这一步多余但实际团队协作中版本号写清楚能让前端和测试一眼看出当前环境用的是哪版接口定义。package com.example.demo.config; import io.swagger.v3.oas.models.OpenAPI; import io.swagger.v3.oas.models.info.Contact; import io.swagger.v3.oas.models.info.Info; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; Configuration public class OpenApiConfig { Bean public OpenAPI customOpenAPI() { return new OpenAPI() .info(new Info() .title(用户服务 API 文档) .description(面向小程序端、管理后台开放的接口定义) .version(v1.0.0) .contact(new Contact() .name(后端组) .email(backendexample.com))); } }注意这里的OpenAPI类是io.swagger.v3.oas.models.OpenAPI不是老版本里那个不存在的东西。引入包名错了编译直接失败这个最容易一眼看出来但有些人会顺手改成别的类导致后续 bean 注入不了。3.4 Controller 里放一套标准注解Controller 本身不复杂关键是注解要放到正确位置。我写了一个用户查询接口做演示package com.example.demo.controller; import com.example.demo.common.Result; import io.swagger.v3.oas.annotations.Operation; import io.swagger.v3.oas.annotations.Parameter; import io.swagger.v3.oas.annotations.tags.Tag; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.PathVariable; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RestController; import java.util.List; RestController RequestMapping(/api/users) Tag(name 用户管理, description 用户模块的查询与管理接口) public class UserController { GetMapping(/{id}) Operation(summary 根据ID查询用户, description 返回用户基本信息不包含敏感字段) public ResultUserVO getUser( Parameter(description 用户ID, example 10001) PathVariable(id) Long id) { return Result.success(new UserVO(id, 测试用户)); } GetMapping Operation(summary 查询用户列表) public ResultListUserVO listUsers() { return Result.success(List.of()); } }Tag写在类上Operation写在方法上Parameter写在参数上。这套注解跟 Swagger2 时代习惯完全不同但结构很清晰一个类对应一个模块一个方法对应一个接口。只要 Controller 被正常扫描Knife4j 就能自动把接口信息渲染到页面上。3.5 启动后先看哪个地址跑起来以后有几个地址需要熟悉地址作用/doc.htmlKnife4j 增强版 UI日常主要看这个/v3/api-docs原始 OpenAPI JSON 数据/swagger-ui/index.htmlspringdoc 自带的原生 Swagger UI 页面我先看的永远是/v3/api-docs。这个页面返回的是 JSON 纯数据如果这里的paths里有接口说明扫描正常如果/doc.html打不开问题出在 UI 层如果 JSON 里paths是空的说明 Controller 扫描配置有问题。这个排查顺序能帮你省下大量时间。4. 文档打不开或接口空列表按这个次序排查项目跑起来后真正麻烦的往往不是配置过程而是启动成功但文档页面表现不正常。我把自己碰过的几种典型情况汇总一下每类问题后面都会给排查方向和解决办法。4.1 先把问题定位到 UI 层还是数据层出现异常时先别盯着/doc.html的报错猜原因。按我的习惯第一步就是打开/v3/api-docs看它能不能正常返回 JSON。这一步能把问题切成两大块JSON 正常说明后端接口扫描没问题UI 加载不出来多半是静态资源被拦截JSON 本身返回空paths那就是扫描范围或路径匹配的锅。我还见过一种情况是/v3/api-docs返回了 401这就直接说明安全策略把文档接口拦了跟 Knife4j 本身的配置毫无关系。先去调 Spring Security 或网关白名单再回来检查 UI。4.2 Spring Security 拦住了静态资源这是最常见的一类问题。Spring Boot 3 里的 Spring Security 6 写法变了安全过滤链如果不放行文档相关路径那/doc.html要么直接 401要么页面能出来但里面的 CSS/JS 被拦导致样式全丢。下面是一个最精简的安全放行配置片段Bean public SecurityFilterChain filterChain(HttpSecurity http) throws Exception { http .csrf(AbstractHttpConfigurer::disable) .authorizeHttpRequests(auth - auth .requestMatchers( /doc.html, /webjars/**, /v3/api-docs/**, /swagger-ui/**, /swagger-resources/**, /favicon.ico ).permitAll() .anyRequest().authenticated() ); return http.build(); }Spring Security 6 里.antMatchers已经被更直白的.requestMatchers取代。如果你还沿用老写法编译或启动阶段可能就直接报错。放行路径别偷懒/webjars/**漏掉的话Knife4j UI 会白屏得非常彻底。4.3 包扫描和路径匹配把接口藏起来了如果/v3/api-docs返回正常但paths是空对象绝大多数情况是springdoc.packages-to-scan配错了。比如 Controller 在com.example.demo.controller你写成了com.example.demo有的版本也能扫到但如果你项目结构更复杂包路径差一级就可能漏掉整个模块。还有paths-to-match这东西更像是一道闸门。假设你配的是/api/admin/**而接口实际在/api/user/**那即使 Controller 被扫描到了openapi 数据里也不会展示这些接口。我建议没有特殊需求时先写成/**把闸门放开确认所有接口都能看到后再按模块去收敛。这里有个实用技巧如果你想快速验证扫描规则直接把springdoc.packages-to-scan改大扫到启动类所在的根包通常不会有遗漏。如果接口多到需要分类再考虑用分组而不是把扫描范围抠得太细。4.4 MVC 拦截器对 webjars 开火很多项目会自定义 WebMvc 拦截器用来做登录态校验、操作日志记录。Knife4j 的静态资源很多来自/webjars/**路径如果拦截器的排除名单里没加这些路径页面就会出现 CSS 加载不了、控制台一堆 404。排除路径参照下面这样写放在WebMvcConfigurer里registry.addInterceptor(loginInterceptor) .addPathPatterns(/**) .excludePathPatterns( /doc.html, /webjars/**, /v3/api-docs/**, /swagger-ui/**, /swagger-resources/**, /favicon.ico );拦截器跟 Spring Security 是两个层面的东西有人配好了 Security 放行但没配拦截器一样打不开页面。检查的时候记得两层都看一眼。4.5 context-path、网关前缀和资源相对路径如果应用配置了server.servlet.context-path比如/app那 Knife4j 页面访问地址就是/app/doc.html。正常情况下 Knife4j 会自动基于上下文生成资源引用路径问题大多出在网关或 nginx 二次改写前缀的场景。举个例子网关把请求从/gateway/app/doc.html改写成/app/doc.html再转发到后端前端 JS 在做资源拼接时可能认为当前上下文是/gateway/app于是去请求/gateway/app/webjars/**而后端根本没有这个路径页面就崩了。经验是网关层尽量透传原始路径不要层层剥离前缀如果实在有特殊需求建议先检查页面最终的静态资源 URL 和后端实际暴露路径是否对齐。4.6 Spring Boot 3.2 和旧版本 Knife4j 的兼容问题我遇到过 Spring Boot 从 3.1 升到 3.2 后Knife4j 页面打不开控制台出现NoResourceFoundException指向静态资源处理器。排查下来不是代码问题而是 Knife4j 4.3.0 携带的 springdoc 版本对 Spring Boot 3.2 的静态资源匹配逻辑兼容性不够。解决方案就是升级 Knife4j 到 4.4.0 以上。升级之后还是同样的代码和配置/doc.html直接恢复。这也再次验证了我前面的观点Spring Boot 3.2 及以上版本不要在 Knife4j 版本上太保守。4.7 一个典型问题速查表现象可能原因处理方向/doc.html白屏Security 或拦截器拦截/webjars/**放行静态资源路径JSON 正常但 UI 空静态资源 404检查拦截器和反向代理前缀JSON 的 paths 空包扫描或路径匹配不对调整packages-to-scan和paths-to-match启动报类冲突同时存在 Springfox 和 Knife4j移除 Springfox 依赖Boot 3.2 静态资源报错Knife4j 版本太老升级到 4.4.0 以上5. 三个高频进阶功能Bearer 认证、分组、生产开关基础跑通之后绝大多数项目还需要解决三个问题接口文档里带 Token 调试、按模块拆分组、生产环境控制文档能不能看。这三个功能属于“不一定当场需要但用到时能大大提升效率”的类型。5.1 在 Knife4j 里注入全局 Bearer Token现在很多后端接口用 JWT 做认证前端在 Knife4j 页面调试时如果不能让每个请求自动带上Authorization: Bearer xxx体验非常割裂。Knife4j 4.x 支持 OpenAPI 3 的 Security Scheme只需要在配置类里声明一下。修改前面的OpenApiConfigConfiguration public class OpenApiConfig { Bean public OpenAPI customOpenAPI() { String schemeName bearerAuth; return new OpenAPI() .components(new Components() .addSecuritySchemes(schemeName, new SecurityScheme() .type(SecurityScheme.Type.HTTP) .scheme(bearer) .bearerFormat(JWT))) .addSecurityItem(new SecurityRequirement().addList(schemeName)) .info(new Info() .title(用户服务 API 文档) .version(v1.0.0)); } }配置完之后Knife4j 页面右上角会多出一个 Authorize 按钮点进去把 Token 填好后面请求就能自动带认证头。这个配置对没有安全需求的项目是多余的但如果你的接口统一走 JWT建议从第一天就加上。5.2 给文档站本身再加一道 Basic 登录有些团队不希望文档完全公开但又不想为了文档单独接一套权限系统。Knife4j 提供了内置的 Basic 认证开关配置非常简单knife4j: basic: enable: true username: api-docs password: ${DOC_PASSWORD}注意这里的密码如果直接写在 yaml 里会进入版本库团队内部还好对外开放的项目建议通过环境变量注入。打开/doc.html时浏览器会先弹出一个登录框认证通过后才能看到文档内容。这个方案适合做内部测试环境的轻量保护不适合当生产环境的安全边界。5.3 按模块拆分组避免文档变成一个巨型列表当接口数量上来以后所有 Controller 挤在一个文档里会非常难用。拆分组有两种常见方式你可以按取向选择。一种是用 yaml 配置快速拆分springdoc: group-configs: - group: 用户端 packages-to-scan: com.example.demo.controller.user - group: 管理端 packages-to-scan: com.example.demo.controller.admin另一种是用 Java Bean 做更灵活的路径匹配Bean public GroupedOpenApi userApi() { return GroupedOpenApi.builder() .group(用户端) .pathsToMatch(/api/user/**) .packagesToScan(com.example.demo.controller.user) .build(); } Bean public GroupedOpenApi adminApi() { return GroupedOpenApi.builder() .group(管理端) .pathsToMatch(/api/admin/**) .packagesToScan(com.example.demo.controller.admin) .build(); }拆分之后Knife4j 页面左侧会出现分组下拉选择。这样前端可以直接切到自己关心的模块不用在几百个接口里反复搜索。需要提醒的是分组和springdoc.packages-to-scan的配置最好不要同时写得太复杂确定一种主方式否则会出现同一个接口被重复扫描进多个分组的情况。5.4 生产环境一键关闭文档文档工具是双刃剑开发环境可以开生产环境最好关。Knife4j 本身提供了两个开关knife4j: production: true springdoc: api-docs: enabled: falseknife4j.production设置为 true 后文档访问入口会关闭springdoc.api-docs.enabled设置为 false 后/v3/api-docs这个数据接口也会失效。两者一起配置基本可以达到生产环境不出文档的效果。如果你的生产环境希望保留文档但只对特定运维人员开放那就别用这个全局开关改用 5.2 里的 Basic 认证更合适。这个取舍取决于团队的管理风格没有绝对标准。6. 从 Springfox 老注解迁到 OpenAPI 3 的机械清单最后说一件很多人到了真正迁移时才发现的事Knife4j 4.x 和 Spring Boot 3 配套注解体系已经不是原来那套 Swagger2 注解了。项目越大这种替换越容易出错。6.1 注解对应表直接照着改我整理了一张最常见的对应关系绝大多数项目迁移时只需要做这些替换Springfox / Swagger2OpenAPI 3 / Knife4jApiTagApiOperationOperationApiParamParameterApiModelSchemaApiModelPropertySchema(description ...)ApiImplicitParamParameterApiImplicitParamsParametersApiResponseApiResponse包名变了ApiResponse是最容易迷惑的地方因为注解短名没变但 import 包从io.swagger.annotations.ApiResponse换成了io.swagger.v3.oas.annotations.responses.ApiResponse。如果只改注解不换包启动不报错文档里却永远看不到响应说明。6.2 更新 import 是重点不是细节Springdoc 只认io.swagger.v3.oas.annotations下的注解这一点决定了你必须把每个 Controller 和 DTO 类上的 import 全部换掉。我见过一个项目从旧框架迁移过来第一轮只改了依赖坐标启动一切正常结果打开文档发现所有接口都没有描述连接口名都是空白的。查下来才发现代码里还在用io.swagger.annotations.ApiOperation这相当于把 Windows 的快捷键带到了 Mac 上用看着熟悉实际无效。需要经常用到的 import 大概这些import io.swagger.v3.oas.annotations.Operation; import io.swagger.v3.oas.annotations.Parameter; import io.swagger.v3.oas.annotations.tags.Tag; import io.swagger.v3.oas.annotations.media.Schema; import io.swagger.v3.oas.annotations.responses.ApiResponse; import io.swagger.v3.oas.annotations.responses.ApiResponses;6.3 DTO 字段上的 Schema 写法老项目里ApiModelProperty的写法是这样的ApiModelProperty(value 手机号, example 13800000000) private String mobile;迁移到 OpenAPI 3 后只要把注解换成Schema几乎可以平替Schema(description 手机号, example 13800000000) private String mobile;如果字段是必填项可以用requiredMode Schema.RequiredMode.REQUIRED比老版本的required true语义更明确。对于使用ResultT这类统一响应体的项目建议把泛型里的 T 落到具体 VO 类而不是用 Map 返回否则 springdoc 无法准确推导字段结构文档里只会看到Map两个字母完全没有字段信息。6.4 统一响应体的泛型推导值得花半小时检查很多团队的 Controller 返回结构都是统一的比如ResultUserVO、PageResultOrderVO。springdoc 对泛型推导是支持的但前提是泛型参数在返回值类型里明确出现。如果你偷懒把方法返回类型写成Result不带尖括号或者用MapString, Object拼数据那文档里的 response schema 会非常难看。我在项目里处理过一个接口返回类型是ResultMapString, ObjectKnife4j 页面渲染出来就是一个光秃秃的Map没有任何字段说明。后来把接口改成真正的 VO 类文档立刻清晰很多。这件事不算 Knife4j 的配置问题而是规范问题值得在代码评审时统一要求。最后分享一个我自己养成的习惯每次升级依赖后第一件事不是打开doc.html看 UI而是先请求/v3/api-docs确认paths里的数据是否齐全。只要这层数据是对的UI 层的问题通常几分钟就能定位如果数据本身缺接口那就回到扫描配置和注解检查。另一件顺手做掉的小事是给每个Operation的 description 写一句话业务语义而不是只填“接口描述”四个字。短时间内看不出差别等项目过几千行接口描述以后你会感谢当初那个没偷懒的自己。