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。