Spring Boot 2.0集成Swagger UI异常：接口未显示且报404错误

阿华AIGC实验室

2026-5-21

Spring Boot 2.0集成Swagger接口不显示/404问题排查方案

我来帮你排查下这个问题，Spring Boot 2.0和Swagger的集成有几个容易踩坑的点，咱们一步步来：

1. 先检查依赖是否匹配

Spring Boot 2.0对Swagger2（springfox系列）的兼容版本主要是2.9.x，太高或者太低都可能出现资源找不到的问题。如果是Maven项目，确保你的pom.xml里有这两个依赖：

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

Gradle项目的话，对应配置是：

implementation 'io.springfox:springfox-swagger2:2.9.2'
implementation 'io.springfox:springfox-swagger-ui:2.9.2'

2. 确认Swagger配置类是否正确

必须创建一个带@EnableSwagger2注解的配置类，并且正确配置Docket实例，重点要注意controller的包路径是否扫描正确——如果包路径写错，Swagger会找不到你的接口：

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                // 替换成你项目中controller所在的实际包路径
                .apis(RequestHandlerSelectors.basePackage("com.your-project.controller"))
                .paths(PathSelectors.any())
                .build();
    }
}

3. 检查静态资源映射配置

Spring Boot 2.0的默认静态资源规则可能会拦截Swagger的UI资源，如果你自定义了WebMvc配置，需要手动放行Swagger的静态文件：

import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

@Configuration
public class WebMvcConfig implements WebMvcConfigurer {
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        // 放行Swagger UI页面
        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");
        // 放行Swagger依赖的webjars资源
        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
}

4. 若使用Spring Security，需放行Swagger相关路径

如果你的项目集成了Spring Security，默认会拦截所有请求，必须手动放行Swagger的核心路径：

import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
import org.springframework.security.config.annotation.web.configuration.WebSecurityConfigurerAdapter;

@EnableWebSecurity
public class SecurityConfig extends WebSecurityConfigurerAdapter {
    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http.authorizeRequests()
                // 放行所有Swagger相关的请求路径
                .antMatchers(
                    "/swagger-ui.html",
                    "/swagger-resources/**",
                    "/webjars/**",
                    "/v2/api-docs"
                ).permitAll()
                // 其他请求按需配置权限
                .anyRequest().authenticated();
    }
}