Springfox/Springfox项目整合Spring Security后Swagger-UI访问异常的解决方案

问题背景

在Spring Boot 3和Spring Security 6集成的项目中，开发者经常遇到配置Swagger-UI后无法访问的问题。典型表现为访问/swagger-ui.html路径时出现HTTP 403错误，即使已在安全配置中显式放行了该路径。

核心问题分析

1. 路径匹配问题：Spring Security 6.x版本对请求匹配逻辑进行了重构，传统的antMatchers()已被requestMatchers()替代
2. 静态资源拦截：Swagger-UI由多个静态资源组成（HTML/JS/CSS），仅放行HTML入口可能不够
3. 版本适配问题：Spring Boot 3.x与较新Spring Security版本对静态资源处理方式有变化

完整解决方案

方案一：WebSecurityCustomizer方式（推荐）

@Bean
public WebSecurityCustomizer webSecurityCustomizer() {
    return web -> web.ignoring().requestMatchers(
            "/swagger-ui/**",
            "/v3/api-docs/**",
            "/swagger-ui.html",
            "/swagger-resources/**",
            "/webjars/**"
    );
}

方案二：HttpSecurity配置方式

@Bean
SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
    http.authorizeHttpRequests(auth -> auth
            .requestMatchers(
                "/swagger-ui/**",
                "/v3/api-docs/**",
                "/swagger-resources/**"
            ).permitAll()
            // 其他安全配置...
        );
    return http.build();
}

技术要点说明

1. 多路径放行必要性：

   • /swagger-ui.html：UI入口页面
   • /swagger-ui/**：静态资源路径
   • /v3/api-docs/**：OpenAPI规范端点
   • /webjars/**：WebJars资源路径

2. 版本适配建议：

   • Spring Boot 3.x建议使用SpringDoc OpenAPI替代传统Springfox
   • 若必须使用Springfox，需确保依赖版本兼容

3. 安全策略考量：

   • 生产环境应通过环境变量控制Swagger的启用
   • 可结合@Profile("dev")限定配置类生效范围

最佳实践建议

1. 对于新项目，建议直接采用SpringDoc OpenAPI（springdoc-openapi-starter-webmvc-ui）
2. 维护项目升级时，注意检查以下配置：
   • 静态资源处理器配置
   • 内容安全策略(CSP)设置
   • 跨域配置（如前端单独部署时）
3. 可通过自定义SecurityFilterChain调整过滤顺序，确保资源请求不被JWT等过滤器拦截

常见误区

1. 仅放行HTML入口：忽略关联的JS/CSS资源会导致页面加载不完整
2. 过度放行：直接禁用所有安全配置会带来安全隐患
3. 路径拼写错误：注意新版Swagger的静态资源路径变化