1. 概述
在本教程中，我們將學習如何配置 Spring Security 以允許在 Spring Boot 3 應用程序中訪問 Swagger UI。
Swagger UI 是一個用於文檔化 API 的工具。它提供了一個用户友好的界面，用於與 API 交互和測試端點。但是，當我們啓用 Spring Security 在我們的應用程序中時，由於安全限制，Swagger UI 變得不可訪問。
我們將探索如何在 Spring Boot 3 應用程序中設置 Swagger 並配置 Spring Security 以允許訪問 Swagger UI。
2. 代碼設置
我們首先設置應用程序。我們將添加必要的依賴項並創建一個簡單的控制器。我們將配置 Swagger 並測試 Swagger UI 是否可訪問。然後我們將通過配置 Spring Security 來修復它。
2.1. 添加 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>
springdoc-openapi-starter-webmvc-ui 是一個 Springdoc OpenAPI 庫，它封裝了 Swagger。它包含設置 Swagger 到應用程序所需的依賴項和註釋。
spring-boot-starter-security 依賴項為應用程序提供 Spring Security。 當我們添加此依賴項時，Spring Security 默認啓用並阻止所有 URL 的訪問。
spring-boot-starter-web 依賴項用於創建 API。
2.2. 控制器
接下來，讓我們創建一個具有端點的控制器:
@RestController
public class HelloController {
@GetMapping("/hello")
public String hello() {
return "Hello, World!";
}
}
當我們調用 hello 端點時，它將返回字符串 “Hello, World!”。
3. 配置 Swagger
接下來，讓我們配置 Swagger。我們將設置配置以啓用 Swagger，並向控制器添加註釋。
3.1. 配置類
為了配置 Swagger，我們需要創建一個配置類：
@Configuration
public class SwaggerConfig {
@Bean
public GroupedOpenApi publicApi() {
return GroupedOpenApi.builder()
.group("public")
.pathsToMatch("/**")
.build();
}
}
在這裏，我們創建了一個 SwaggerConfig 類並定義了一個 publicApi() 方法，該方法返回一個 GroupedOpenApi Bean。
我們在方法中定義了一個組 public，並指定了路徑模式為 “/**”。這意味着應用程序中的所有端點都將包含在此組中。
3.2. Swagger 註解
接下來，讓我們向控制器添加 Swagger 註解：
@Operation(summary = "Returns a Hello World message")
@GetMapping("/hello")
public String hello() {
return "Hello, World!";
}
我們向 hello() 方法添加了 @Operation 註解，用於描述端點。此描述將在 Swagger UI 中顯示。
3.3. 測試
現在，讓我們運行應用程序並測試 Swagger UI。默認情況下，Swagger UI 可在 http://localhost:8080/swagger-ui/index.html 處訪問：
在上面的圖像中，我們可以看到 Swagger UI 無法訪問。相反，我們被提示輸入用户名和密碼。 Spring Security 想要在允許訪問 URL 之前對用户進行身份驗證。
4. 配置 Spring Security 以允許 Swagger UI
現在，讓我們配置 Spring Security 以允許訪問 Swagger UI。 我們將研究兩種實現此目的的方法：使用 SecurityFilterChain 和 WebSecurityCustomizer。
4.1. 使用 WebSecurityCustomizer
使用 WebSecurityCustomizer 接口排除 Spring Security 中路徑的最簡單方法是。 我們可以使用此接口禁用 Spring Security 上的指定 URL。
讓我們在配置類中定義類型為 WebSecurityCustomizer 的 Bean：
@Configuration
public class SecurityConfig {
@Bean
public WebSecurityCustomizer webSecurityCustomizer() {
return (web) -> web.ignoring()
.requestMatchers("/swagger-ui/**", "/v3/api-docs*/**");
}
}
@Configuration 註解標記類為配置類。 接下來，我們定義類型為 WebSecurityCustomizer 的 Bean。
在這裏，我們使用了 lambda 表達式來定義 WebSecurityCustomizer 的實現。 我們使用了 ignoring() 方法來排除 Swagger UI URL /swagger-ui/** 和 /v3/api-docs*/** 從安全配置中。
這在我們需要忽略 URL 上所有安全規則時非常有用。 僅在 URL 內部且未公開為無安全規則應用的情況下才建議這樣做。
4.2. 使用 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();
}
此方法配置安全過濾器鏈以允許訪問 Swagger UI URL：
- 我們使用了 authorizeHttpRequests() 方法來定義授權規則。
- requestMatchers() 方法用於匹配 URL。 我們指定了 Swagger UI URL 模式 /swagger-ui/** 和 /v3/api-docs*/**。
- /swagger-ui/** 是 Swagger UI 的 URL 模式，而 /v3/api-docs*/** 是 Swagger 調用以獲取 API 信息中的 URL 模式。
- 我們使用了 permitAll() 方法來允許訪問這些 URL 而無需身份驗證。
- 最後，我們返回了 http.build() 方法來構建安全過濾器鏈。
這是允許對某些 URL 模式進行未經身份驗證請求的推薦方法。 這些 URL 將包含 Spring Security 標頭在響應中。 但是，它們將不需要用户身份驗證。
4.3. 測試
現在，讓我們運行應用程序並再次測試 Swagger UI。 Swagger UI 現在應該可訪問。
正如我們所看到的，頁面是可訪問的，並且包含有關我們的控制器端點的信息。
5. 結論
在本文中，我們學習瞭如何配置 Spring Security 以允許訪問 Spring Boot 3 應用程序中的 Swagger UI。我們探討了如何使用 SecurityFilterChain 接口和 WebSecurityCustomizer 接口從 Spring Security 配置中排除 Swagger UI URL。
