今天又碰到了一个也很折磨人的问题Knife4j 接口文档打不开起因是我在跟课程进度的时候完成了新建员工的操作需要进行接口测试。课程里面使用的是Swagger跟着课程敲下来自信满满打开链接http://localhost:8080/doc.html#/home结果就是显示Knife4j异常就是我寻思直接postman应该也没事儿摸索半天感觉还是没有课程里面的好用一开始我以为只是代码没敲对核对了一下PPT没问题。那就可能是配置问题了排查下来发现根因在Spring Boot、Spring Framework、springdoc、Knife4j 之间的版本兼容性上最开始日志里报的是这样一段警告WARN PageNotFound : No mapping for GET /swagger-resourcesWARN PageNotFound : No endpoint GET /swagger-resources.即Knife4j 前端页面去请求了 /swagger-resources但后端并没有提供这个接口/swagger-resources 这个地址是早期 Swagger2 / Springfox 常见的接口路径。而我当前项目其实已经是在 Spring Boot 3 环境下了按理说应该走的是 OpenAPI3 体系对应接口一般是/v3/api-docs所以项目里很可能混入了旧版 Swagger2 的配置或依赖导致 Knife4j 页面资源和后端实际文档接口不匹配。按照以下方式操作1.查看pom.xml把老依赖清掉springfox-swagger2springfox-swagger-uispringfox-boot-starterknife4j-openapi2-spring-boot-starter2.我的项目是Boot 3这些都容易导致前端资源和后端接口对不上。官方文档也特别提醒 Boot 3 要避免 jar 冲突。改好之后又出现了新的报错我真的是……心态要爆炸了被这些问题困住一晚上此处反复调整心态挣扎0.5h…说明现在项目里用了 Spring Framework 6.2.0但 springdoc-openapi 2.3.0 仍然在调用一个旧的 ControllerAdviceBean(Object) 构造方法而 Spring 6.2 这一侧已经不再按这个方式兼容所以访问 /v3/api-docs 时直接炸掉。这个问题在 springdoc 官方 issue 里有明确记录且被认为和 Spring 6.2 / Boot 3.5.x 的兼容性有关。实在没招了考虑到万一以后又遇到版本不兼容的问题我还是把springboot版本降低到比较稳定的版本吧这一次的根源还得从一开始选择了默认的比较新的SpringBoot的版本说起。。。终于哦对了像这种成熟的项目代码肯定是没问题的出问题肯定就说版本依赖相关的建议大家耐心一点查一查官方说明还有社区讨论。如果你不想查也可以用AI帮忙查一查原因。附上我使用版本号Spring Boot 3.2.5Spring Framework 6.1.xKnife4j 4.4.0
《苍穹外卖》Knife4j 接口文档打不开-Knife4j异常
发布时间：2026/6/11 0:17:23
今天又碰到了一个也很折磨人的问题Knife4j 接口文档打不开起因是我在跟课程进度的时候完成了新建员工的操作需要进行接口测试。课程里面使用的是Swagger跟着课程敲下来自信满满打开链接http://localhost:8080/doc.html#/home结果就是显示Knife4j异常就是我寻思直接postman应该也没事儿摸索半天感觉还是没有课程里面的好用一开始我以为只是代码没敲对核对了一下PPT没问题。那就可能是配置问题了排查下来发现根因在Spring Boot、Spring Framework、springdoc、Knife4j 之间的版本兼容性上最开始日志里报的是这样一段警告WARN PageNotFound : No mapping for GET /swagger-resourcesWARN PageNotFound : No endpoint GET /swagger-resources.即Knife4j 前端页面去请求了 /swagger-resources但后端并没有提供这个接口/swagger-resources 这个地址是早期 Swagger2 / Springfox 常见的接口路径。而我当前项目其实已经是在 Spring Boot 3 环境下了按理说应该走的是 OpenAPI3 体系对应接口一般是/v3/api-docs所以项目里很可能混入了旧版 Swagger2 的配置或依赖导致 Knife4j 页面资源和后端实际文档接口不匹配。按照以下方式操作1.查看pom.xml把老依赖清掉springfox-swagger2springfox-swagger-uispringfox-boot-starterknife4j-openapi2-spring-boot-starter2.我的项目是Boot 3这些都容易导致前端资源和后端接口对不上。官方文档也特别提醒 Boot 3 要避免 jar 冲突。改好之后又出现了新的报错我真的是……心态要爆炸了被这些问题困住一晚上此处反复调整心态挣扎0.5h…说明现在项目里用了 Spring Framework 6.2.0但 springdoc-openapi 2.3.0 仍然在调用一个旧的 ControllerAdviceBean(Object) 构造方法而 Spring 6.2 这一侧已经不再按这个方式兼容所以访问 /v3/api-docs 时直接炸掉。这个问题在 springdoc 官方 issue 里有明确记录且被认为和 Spring 6.2 / Boot 3.5.x 的兼容性有关。实在没招了考虑到万一以后又遇到版本不兼容的问题我还是把springboot版本降低到比较稳定的版本吧这一次的根源还得从一开始选择了默认的比较新的SpringBoot的版本说起。。。终于哦对了像这种成熟的项目代码肯定是没问题的出问题肯定就说版本依赖相关的建议大家耐心一点查一查官方说明还有社区讨论。如果你不想查也可以用AI帮忙查一查原因。附上我使用版本号Spring Boot 3.2.5Spring Framework 6.1.xKnife4j 4.4.0
)
