Spring Boot 3 中配置 Spring Security 允许访问 Swagger UI

1. 概述

本教程将指导你在 Spring Boot 3 应用中配置 Spring Security，使其允许访问 Swagger UI。

Swagger UI 是一个强大的 API 文档工具，提供可视化界面用于接口交互和测试。但当应用启用 Spring Security 后，默认的安全策略会阻止访问 Swagger UI。我们将通过以下步骤解决这个问题：

搭建基础应用环境
配置 Swagger 文档
解决安全限制问题
测试验证结果

2. 项目初始化

2.1. 添加必要依赖

在 pom.xml 中添加以下核心依赖：

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.6.0</version>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-security</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>

⚠️ 关键点说明：

springdoc-openapi-starter-webmvc-ui：集成 Swagger UI 的核心库
spring-boot-starter-security：启用后默认拦截所有 URL
spring-boot-starter-web：构建 REST API 的基础依赖

2.2. 创建测试控制器

@RestController
public class HelloController {
    @GetMapping("/hello")
    public String hello() {
        return "Hello, World!";
    }
}

这个简单的控制器提供一个测试接口，访问时返回 Hello, World!。

3. Swagger 配置

3.1. 创建配置类

@Configuration
public class SwaggerConfig {
    @Bean
    public GroupedOpenApi publicApi() {
        return GroupedOpenApi.builder()
            .group("public")
            .pathsToMatch("/**")
            .build();
    }
}

✅ 配置要点：

创建 GroupedOpenApi Bean 分组管理接口
group("public") 定义分组名称
pathsToMatch("/**") 匹配所有路径

3.2. 添加接口注解

@Operation(summary = "Returns a Hello World message")
@GetMapping("/hello")
public String hello() {
    return "Hello, World!";
}

使用 @Operation 注解为接口添加描述信息，这些信息会显示在 Swagger UI 中。

3.3. 验证初始状态

启动应用后访问 http://localhost:8080/swagger-ui/index.html，会看到：

Spring Security 登录页面

❌ 预期问题：页面被 Spring Security 拦截，要求身份验证

4. 安全配置方案

4.1. 使用 WebSecurityCustomizer（简单粗暴方案）

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

✅ 实现原理：

通过 ignoring() 完全排除指定路径的安全检查
匹配规则：
- /swagger-ui/**：Swagger UI 界面资源
- /v3/api-docs*/**：OpenAPI 文档数据

⚠️ 使用注意：

仅适用于内部环境或可信网络
完全跳过安全检查，生产环境慎用

4.2. 使用 SecurityFilterChain（推荐方案）

@Bean
public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
    http.authorizeHttpRequests(
      authorizeRequests -> authorizeRequests.requestMatchers("/swagger-ui/**")
        .permitAll()
        .requestMatchers("/v3/api-docs*/**")
        .permitAll());

    return http.build();
}

✅ 方案优势：

保留安全头信息（如 XSS 防护等）
仅豁免身份验证，其他安全策略仍生效
生产环境推荐使用

📌 关键配置说明：

permitAll() 允许匿名访问
必须同时豁免两个路径：
- 界面资源：/swagger-ui/**
- API 数据：/v3/api-docs*/**

4.3. 验证配置结果

重启应用后再次访问 Swagger UI：

Swagger UI 成功访问页面

✅ 预期结果：

无需身份验证即可访问
正确显示控制器接口信息
可正常进行接口测试

5. 总结

本教程解决了 Spring Boot 3 中 Spring Security 与 Swagger UI 的集成问题，核心要点：

两种安全配置方案对比：

方案适用场景安全级别推荐度

WebSecurityCustomizer 内部测试低 ⭐⭐

SecurityFilterChain 生产环境高 ⭐⭐⭐⭐⭐

方案	适用场景	安全级别	推荐度
WebSecurityCustomizer	内部测试	低	⭐⭐
SecurityFilterChain	生产环境	高	⭐⭐⭐⭐⭐

关键路径豁免：

/swagger-ui/**     # 界面资源
/v3/api-docs*/**   # API 文档数据

最佳实践建议：
- 开发环境可使用 WebSecurityCustomizer 快速配置
- 生产环境必须使用 SecurityFilterChain
- 豁免路径后仍需监控访问日志

完整代码示例可在 GitHub 获取。

Persistence

REST

Security