Swagger接口文档配置及Springfox教程

本文深入解析了Springfox在不同Spring Boot版本中的配置陷阱与兼容性问题，重点揭示了Spring Boot 2.6+因默认启用`throw-exception-if-no-handler-found`导致Swagger UI 404的根源，并给出精准的`application.yml`修复配置；同时直击常见误区——如错误路径访问（必须用`/swagger-ui/`而非`.html`）、Docket扫描失效原因及泛型Controller适配方案；更关键的是明确指出Spring Boot 3.x与Springfox彻底不兼容的现实：因Jakarta EE 9迁移导致运行时崩溃，无任何绕过方案，必须迁移到springdoc-openapi——文章不仅教你怎么修bug，更帮你避开技术债深坑，让接口文档配置真正省心可靠。

Springfox 3.x 在 Spring Boot 2.6+ 启动就报 NoHandlerFoundException

Spring Boot 2.6 默认启用了 spring.mvc.throw-exception-if-no-handler-found=true，而 Springfox 3.x 的 Docket 注册的静态资源（如 /swagger-ui.html）没被 MVC 资源处理器识别，导致 404 直接抛异常，页面打不开。

• 在 application.yml 中显式关闭该开关：

  spring:
    mvc:
      throw-exception-if-no-handler-found: false
    resources:
      add-mappings: true

• 同时必须保留 spring.resources.add-mappings: true，否则 /webjars/** 路径下的 Swagger UI 静态资源根本不会注册
• 别信某些博客说“加个 @EnableWebMvc 就行”——那会彻底禁用 Spring Boot 的自动配置，得自己配资源处理器，得不偿失

Swagger UI 访问 404，但后端接口能正常返回 JSON

说明 springfox-swagger2 和 springfox-swagger-ui 依赖已生效，但前端资源路径没对上。Springfox 3.x 把 UI 入口从 /swagger-ui.html 改成了 /swagger-ui/（末尾带斜杠），且依赖 /webjars/swagger-ui/index.html 重定向。

• 确认引入的是 springfox-swagger-ui（不是 swagger-ui 单独 jar）
• 访问地址必须是 http://localhost:8080/swagger-ui/，少斜杠、多 .html 或写成 /swagger-ui/index.html 都会 404
• 如果用了网关或反向代理，检查是否过滤了 /webjars/** 路径（Nginx 常见漏配 location /webjars）

Docket 配置里 select().apis() 不生效

常见于扫描不到 Controller——不是注解没加，而是 RequestHandlerSelectors 的匹配逻辑太严格，默认只认 @Api 或 @RestController，但如果你用的是 @Controller + @ResponseBody，它直接跳过。

• 稳妥写法是用 RequestHandlerSelectors.basePackage("com.example.api") 明确指定包路径
• 避免用 any()，它会把 Actuator、Spring Security 的内部 endpoint 也扫进来，生成大量无意义接口
• 如果 Controller 有泛型参数（比如 BaseController），Springfox 3.x 解析可能失败，接口消失——这时只能手动加 @Api 注解兜底

升级到 Spring Boot 3.x 后 Springfox 彻底跑不起来

Springfox 官方早在 2022 年就停止维护，最后一个版本 3.0.0 不支持 Jakarta EE 9+（即 jakarta.* 包名），而 Spring Boot 3.x 强制使用 Jakarta EE 9。编译可能过，但运行时会报 ClassNotFoundException: javax.servlet.http.HttpServletRequest。

• 没有兼容方案，springfox 在 Spring Boot 3.x 环境下就是不可用的
• 必须迁移到 springdoc-openapi-starter-webmvc-ui（即 Swagger 3 / OpenAPI 3 实现）
• 迁移成本不高：删掉所有 springfox 依赖和 @EnableSwagger2、Docket 配置，加上新依赖后 /swagger-ui.html 自动可用（注意路径又变回带 .html 了）

Spring Boot 版本和 Springfox 版本耦合极紧，看错一个 patch 版本（比如 2.6.3 vs 2.6.7）都可能触发资源注册时机问题——别猜，直接查 Springfox 官方兼容表。

今天带大家了解了的相关知识，希望对你有所帮助；关于文章的技术知识我们会一点点深入介绍，欢迎大家关注golang学习网公众号，一起学习编程~