Spring Boot 3中Swagger UI配置Spring Security

在本文中，我们学习了如何配置 Spring Security 让 Spring Boot 3 应用能访问 Swagger UI。我们探讨了如何使用SecurityFilterChain 和 WebSecurityCustomizer 接口从 Spring Security 配置中排除 Swagger UI URL。

在本教程中，我们将学习如何配置 Spring Security 以允许在 Spring Boot 3 应用程序中访问Swagger UI。

Swagger UI 是一种用于记录 API 的工具。它提供了一个用户友好的界面来与 API 和测试端点进行交互。但是，当我们在应用程序中启用Spring Security时，由于安全限制，Swagger UI 变得无法访问。

我们将探讨如何在Spring Boot 3应用程序中设置 Swagger并配置 Spring Security 以允许访问 Swagger UI。

让我们从设置应用程序开始。我们将添加必要的依赖项并创建一个简单的控制器。我们将配置 Swagger 并测试 Swagger UI 是否不可访问。然后我们将通过配置 Spring Security 来修复它。

添加 Swagger 和 Spring Security 依赖项
首先，我们将向 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>

spring-boot-starter-security依赖项  为应用程序提供 Spring Security。 当我们添加此依赖项时，Spring Security 默认启用并阻止对所有 URL 的访问。

创建 API 需要spring-boot-starter-web依赖项。

控制者
接下来，让我们创建一个具有端点的控制器：

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

配置Swagger
接下来，让我们配置 Swagger。我们将设置配置以启用 Swagger 并向控制器添加注释。

配置类
为了配置 Swagger，我们需要创建一个配置类：

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

我们 在方法中定义了一个public组，并将路径模式指定为“ / ”。这意味着应用程序中的所有端点都将包含在此组中。

Swagger 注释
接下来我们给控制器添加Swagger注解：

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

测试
现在，让我们运行应用程序并测试 Swagger UI。默认情况下，Swagger UI 应该可以通过http://localhost:8080/swagger-ui/index.html访问：

但是系统提示我们输入用户名和密码。Spring Security 希望在允许访问 URL 之前对用户进行身份验证。

配置 Spring Security 以允许 Swagger UI
现在，让我们配置 Spring Security 以允许访问 Swagger UI。我们将介绍两种实现此目的的方法：使用SecurityFilterChain 和 WebSecurityCustomizer。

1. 使用WebSecurityCustomizer
从 Spring Security 中排除路径的一个简单方法是使用WebSecurityCustomizer接口。我们可以使用此接口在指定的 URL 上禁用 Spring Security。

让我们 在配置类中定义一个WebSecurityCustomizer类型的 bean：

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

这里，我们使用 lambda 表达式来定义WebSecurityCustomizer 实现。 我们使用 ignoring()方法 从安全配置中 排除 Swagger UI URL  /swagger-ui/ 和 /v3/api-docs/ 。

当我们想忽略某个 URL 上的所有安全规则时，这很有用。仅当 URL 是内部的且不公开时才建议这样做，因为没有安全规则适用于它。 

使用SecurityFilterChain
覆盖 Spring Security 默认实现的另一种方法是定义SecurityFilterChain bean。然后我们可以在提供的实现中允许 Swagger URL。

为此，我们可以定义一个SecurityFilterChain  bean：

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

• 我们使用 authorizeHttpRequests() 方法来定义授权规则。
• requestMatchers  () 方法用于匹配 URL。我们指定了 Swagger UI URL 模式 /swagger-ui/ 和 /v3/api-docs/。
• /swagger-ui/ 是 Swagger UI 的 URL 模式，而 /v3/api-docs/ 是 Swagger 调用来获取 API 信息的 OpenAPI 文档的 URL 模式。
• 我们使用了 permitAll() 方法允许无需身份验证访问这些 URL。
• 最后，我们返回 http.build() 方法来构建安全过滤器链。