Spring Boot集成Swagger后Swagger-ui页面空白问题求助

安全阿岳

2026-8-5

解决Spring Boot集成SpringDoc后Swagger UI空白页问题

针对你遇到的访问http://localhost:8081/swagger-ui.html出现空白页的问题，可通过以下步骤排查解决：

1. 修正Spring Security配置

Spring Security默认开启的CSRF保护会拦截Swagger UI的相关请求，导致页面资源加载失败。同时建议明确放行Swagger相关的路径（避免通配符可能带来的潜在问题）：

@Configuration
@EnableWebSecurity
public class SecurityConfig {
    @Bean
    public SecurityFilterChain configure(HttpSecurity http) throws Exception {
        http
            .csrf().disable() // 关闭CSRF保护，适配Swagger UI的请求特性
            .authorizeRequests()
                // 明确放行Swagger UI和API文档的所有相关路径
                .antMatchers("/swagger-ui/**", "/v3/api-docs/**", "/swagger-ui.html").permitAll()
                .anyRequest().permitAll();
        return http.build();
    }
}

2. 完善SpringDoc配置（可选但推荐）

在application.properties中明确配置SpringDoc的核心参数，确保加载逻辑正常：

server.port=8081
# 指定Swagger UI访问路径
springdoc.swagger-ui.path=/swagger-ui.html
# 启用API文档生成（默认开启，明确配置更稳妥）
springdoc.api-docs.enabled=true
# 指定API文档接口路径（默认值，可按需修改）
springdoc.api-docs.path=/v3/api-docs

3. 处理自定义WebMvc配置（如果存在）

如果项目中自定义了WebMvcConfigurer，需要确保放行Swagger UI的静态资源，否则会导致页面依赖的CSS/JS无法加载：

@Configuration
public class WebMvcConfig implements WebMvcConfigurer {
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/swagger-ui/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/springdoc-openapi-ui/");
    }
}