Swagger报错分析与解决指南
Swagger 是一个强大的 API 文档生成工具，但在实际应用中可能会遇到各种报错，本文将详细解析几种常见的 Swagger 报错，并给出相应的解决方案，通过这些步骤，您能够快速定位并解决问题，确保您的 API 文档顺利生成和访问。
一、Swagger简介
Swagger 是当前世界上最流行的 API 框架之一，采用可视化的 RestFul 风格，是一种 API 文档在线自动生成工具，它能够在前后端分离开发中，帮助前端人员及时了解后端提供的接口，从而减少沟通成本。
二、常见报错及解决方法
1.路径匹配错误
报错信息：
- Failed to start bean 'documentationPluginsBootstrapper'; nested exception is java.lang.NullPointerException
原因分析：
Springfox 使用的路径匹配是基于AntPathMatcher 的，而 Spring Boot 2.6.X 使用的是PathPatternMatcher。
解决方法：
方法一：添加注解
在配置类上添加@EnableWebMvc 注解来改变匹配规则。
- @Configuration
- @EnableSwagger2
- @EnableWebMvc
- public class SwaggerConfig { ... }
方法二：修改配置文件
在application.yaml 或application.properties 文件中添加以下语句：
- spring.mvc.pathmatch.matchingstrategy=ant_path_matcher
或者：
- spring.mvc.pathmatch.matchingstrategy=ant_path_matcher
方法三：降低版本
降低 SpringFox 的版本至 2.5.* 版本即可。
2.目录结构问题
报错信息：
- This application has no explicit mapping for /error, so you are seeing this as a fallback.
原因分析：
idea 的目录结构出现问题，SpringApplication 的启动类应该在最外层，包含所有子包，初学者很容易犯的错误！路径请求出现问题，找不到请求所对应的真实路径。
解决方法：
实现WebMvcConfigurer 类，重写addResourceHandlers 接口，代码结构如下：
- @EnableWebMvc
- @Configuration
- @EnableSwagger2
- public class SwaggerConfig implements WebMvcConfigurer {
- @Override
- public void addResourceHandlers(ResourceHandlerRegistry registry) {
- registry.addResourceHandler("/**").addResourceLocations("classpath:/METAINF/resources/");
- }
- }
3.依赖问题
报错信息：
引入三方 UI 依赖（如 Knife4j）时，访问doc.html 报错。
原因分析：
可能是当前环境拦截了 Swagger 默认的静态资源。
解决方法：
在配置类文件中实现WebMvcConfigurer 接口并重写addResourceHandlers 方法：
- @Configuration
- public class WebMvcConfig implements WebMvcConfigurer {
- @Override
- public void addResourceHandlers(ResourceHandlerRegistry registry) {
- registry.addResourceHandler("/swaggerui/**")
- .addResourceLocations("classpath:/METAINF/resources/webjars/springfoxswaggerui/");
- registry.addResourceHandler("/swaggerui.html").addResourceLocations("classpath:/METAINF/resources/");
- registry.addResourceHandler("/doc.html").addResourceLocations("classpath:/METAINF/resources/");
- registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/METAINF/resources/webjars/");
- }
- }
4.权限受限无法访问
原因分析：
项目使用了 Spring Security，但没有对 Swagger 的资源路径进行匿名访问配置。
解决方法：
确保 Swagger 的资源路径被允许匿名访问，
- @Configuration
- @EnableWebSecurity
- public class SecurityConfig extends WebSecurityConfigurerAdapter {
- @Override
- protected void configure(HttpSecurity http) throws Exception {
- http.authorizeRequests()
- .antMatchers("/swaggerui.html", "/webjars/", "/v2/", "/swaggerresources/**").permitAll()
- .anyRequest().authenticated();
- }
- }
5.Controller 注解使用错误
原因分析：
错误的使用了@Controller 注解，应该使用@RestController。
解决方法：
将控制器中的@Controller 改为@RestController：
- @RestController
- public class MyController { ... }
三、FAQs
Q1：如何更改 Swagger 的版本？
A1：在 Maven 项目的pom.xml 文件中修改 Swagger 相关依赖的版本，要使用 2.9.2 版本，可以这样配置：
- <dependency>
- <groupId>io.springfox</groupId>
- <artifactId>springfoxswagger2</artifactId>
- <version>2.9.2</version>
- </dependency>
- <dependency>
- <groupId>io.springfox</groupId>
- <artifactId>springfoxswaggerui</artifactId>
- <version>2.9.2</version>
- </dependency>
如果需要迁移到新版本，请参考官方文档进行调整。
Q2：如何解决 Swagger UI 界面无法访问的问题？
A2：确保正确配置了WebMvcConfigurer 并重写了addResourceHandlers 方法，检查是否遗漏了必要的依赖或注解，如@EnableSwagger2 和@EnableWebMvc，确认访问路径是否正确，通常为http://localhost:8080/swaggerui/index.html。
