知識庫 / Spring / Spring Security RSS 訂閱

1. 概述

OpenAPI 是一種語言無關、平台無關的規範，它對 REST API 進行標準化。OpenAPI 使用户能夠輕鬆理解 API，而無需深入研究代碼。 Swagger-UI 可以從該 OpenAPI 規範生成可視化文檔，從而幫助可視化和測試 REST API。

在本教程中，讓我們學習如何生成 OpenAPI 文檔、測試 REST API，以及使用 JWT 身份驗證配置我們的 OpenAPI，在 Spring Boot 應用程序中使用 Springdoc-OpenAPI。

2. Swagger-UI

Swagger-UI 是一系列 HTML、JavaScript 和 CSS 文件，它會根據 OpenAPI 規範生成用户界面。讓我們使用 Springdoc-OpenAPI 庫來自動化生成 REST API 的 OpenAPI 文檔，並使用 Swagger-UI 來可視化這些 API。

編寫 OpenAPI 文檔規範在應用程序 API 數量不斷增加時可能會具有挑戰性。Springdoc-OpenAPI 幫助我們自動生成 OpenAPI 文檔。此外，讓我們嘗試使用該庫並生成 OpenAPI 文檔。

2.1. 依賴項

首先，讓我們添加 Springdoc-OpenAPI 依賴項：

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.7.0</version>
</dependency>

此依賴項還為我們的 Spring Boot 應用程序添加了 Swagger-UI Web 依賴項。

2.2. 配置

接下來，啓動應用程序，並在瀏覽器中輸入 URL http://localhost:8080/swagger-ui.html。

作為結果，我們得到 Swagger-UI 頁面：

同樣，OpenAPI v3.0 文檔將在 http://localhost:8080/v3/api-docs 處提供。

此外，我們還將使用 @OpenAPIDefinition 註解，為我們的 User API 添加描述、服務條款和其他元數據：

@Configuration
@OpenAPIDefinition(
  info =@Info(
    title = "User API",
    version = "${api.version}",
    contact = @Contact(
      name = "Baeldung", email = "[email protected]", url = "https://www.baeldung.com"
    ),
    license = @License(
      name = "Apache 2.0", url = "https://www.apache.org/licenses/LICENSE-2.0"
    ),
    termsOfService = "${tos.uri}",
    description = "${api.description}"
  ),
  servers = @Server(
    url = "${api.server.url}",
    description = "Production"
  )
)
public class OpenAPISecurityConfiguration {}

此外，我們還可以外部化配置和元信息。例如，可以在 application.properties 或 application.yaml 文件中定義 api.version、tos.uri 和 api.description。

2.3. 測試

最後，讓我們測試 Swagger-UI 並檢查 OpenAPI 文檔。

為此，啓動應用程序並打開 URL http://localhost:8080/swagger-ui/index.html 以訪問 Swagger-UI：

同樣，OpenAPI 文檔將在 http://localhost:8080/v3/api-docs 上可用：

{
    "openapi": "3.0.1",
    "info": {
      "title": "User API",
      "termsOfService": "terms-of-service",
     ...
     ...
}

3. JWT 身份驗證

Springdoc-OpenAPI 根據我們的應用程序 REST API 生成文檔。 此外，可以使用 Springdoc-OpenAPI 註解自定義這些文檔。

在本部分，我們將學習如何為我們的 OpenAPIs 配置基於 JWT 的身份驗證。

我們可以按操作、類或全局級別配置 JWT 身份驗證。

3.1. 針對操作的配置

首先，我們只對特定操作聲明 JWT 認證。請定義以下配置：

@Configuration
@SecurityScheme(
  name = "Bearer Authentication",
  type = SecuritySchemeType.HTTP,
  bearerFormat = "JWT",
  scheme = "bearer"
)
public class OpenAPI30Configuration {}

@SecurityScheme 註解將 securitySchemes 添加到 OneAPI 規範的 components 部分。 @SecurityScheme 定義了一個可以用於我們 API 的安全機制。 支持的安全方案包括 APIKey、HTTP 身份驗證（基本和 Bearer）、OAuth2 和 OpenID Connect。 在此情況下，我們使用 HTTP Bearer 身份驗證 作為我們的安全方案。

對於基於 HTTP Bearer 令牌的身份驗證，我們需要將安全方案選擇為 bearerAuth，並選擇 JWT 作為載體格式。

由於我們希望僅保護特定操作，因此需要指定需要身份驗證的操作。對於操作級別的身份驗證，我們應該在操作上使用 @SecurityRequirement 註解：

@Operation(summary = "Delete user", description = "Delete user")
@SecurityRequirement(name = "Bearer Authentication")
@DeleteMapping
description = "A JWT token is required to access this API...",
public String deleteUser(Authentication authentication) {}

配置完成後，讓我們重新部署應用程序並訪問 URL http://localhost:8080/swagger-ui.html:

點擊 圖標會打開登錄對話框，供用户提供訪問令牌以調用操作:

對於此示例，可以通過提供 john/password 或 jane/password 到 authentication API 獲取 JWT 令牌。

獲得 JWT 令牌後，可以將它輸入 value 文本框，然後單擊 Authorize 按鈕，最後單擊 Close 按鈕:

在 JWT 令牌到位後，讓我們調用 deleteUser API:

結果，我們看到操作將提供 JWT 令牌，正如 圖標所指示，Swagger-UI 將此令牌作為 HTTP Bearer 在 Authorization 頭部提供。 最終，在配置到位後，我們可以成功調用受保護的 deleteUser API。

到目前為止，我們已經配置了操作級別安全配置。 同樣，讓我們檢查 OpenAPI JWT 安全類和全局配置。

3.2. 類級別配置

同樣，我們可以為類中的所有操作提供 OpenAPI 認證。在包含所有 API 的類上聲明 @SecurityRequirement 註解。 這樣做將為該類中的所有 API 提供認證：

@RequestMapping("/api/user")
@RestController
@SecurityRequirement(name = "bearerAuth")
@Tag(name = "User", description = "The User API. Contains all the operations that can be performed on a user.")
public class UserApi {}

因此，這種配置使 UserApi 類中的所有操作都具備安全性。 鑑於該類有兩個操作，Swagger-UI 的外觀如下：

3.3 全局配置

通常，我們傾向於將 OpenAPI 認證應用於應用程序中的所有 API。 對於這些情況，可以使用 Spring 的 @Bean 註解在全局級別聲明安全性：

@Configuration
public class OpenAPI30Configuration {
@Bean
public OpenAPI customizeOpenAPI() {
    final String securitySchemeName = "bearerAuth";
    return new OpenAPI()
      .addSecurityItem(new SecurityRequirement()
        .addList(securitySchemeName))
      .components(new Components()
        .addSecuritySchemes(securitySchemeName, new SecurityScheme()
          .name(securitySchemeName)
          .type(SecurityScheme.Type.HTTP)
          .scheme("bearer")
          .bearerFormat("JWT")));
    }
}

使用此全局配置，Springdoc-OpenAPI 會將 JWT 認證配置到應用程序中的所有 OpenAPIs。

讓我們嘗試調用 GET API。

最終，我們收到 HTTP 401 未授權 錯誤。 API 已被保護，並且我們沒有提供 JWT 令牌。 接下來，讓我們提供 JWT 令牌並檢查行為。

點擊 授權 按鈕並提供 JWT 令牌以調用操作。 我們可以從 swagger 控制枱中提供的身份驗證 API 獲取 bearer 令牌：

最後，在配置了 JWT 令牌後，讓我們重新調用 API：

此時，使用正確的 JWT 令牌，我們可以成功調用我們的受保護 API。

4. 結論

在本教程中，我們學習瞭如何將 JWT 身份驗證配置到我們的 OpenAPI 中。Swagger-UI 提供了一個工具，用於根據 OneAPI 規範記錄和測試 REST API。Swaggerdoc-OpenAPI 工具幫助我們根據 Spring Boot 應用程序中包含的 REST API 生成該規範。