為 OpenAPI 配置 JWT 身份驗證

一、概述

OpenAPI是一種與語言無關且獨立於平台的規範，用於標準化 REST API。 OpenAPI 使用戶無需深入研究代碼即可輕鬆理解 API。 Swagger-UI從這個 OpenAPI 規範生成可視化文檔，幫助可視化和測試 REST API。

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

2. Swagger-UI

Swagger-UI 是 HTML、Javascript 和 CSS 文件的集合，可生成基於 OpenAPI 規範的用戶界面。讓我們使用 Springdoc-OpenAPI 庫為 REST API 自動生成 OpenAPI 文檔，並使用 Swagger-UI 來可視化這些 API。

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

2.1。依賴項

直接，讓我們從添加Springdoc-OpenAPI依賴項開始：

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

此依賴項還將 Swagger-UI web-jars 添加到我們的 Spring Boot 應用程序中。

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 [email protected](
 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 文檔。

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

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

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

3.智威湯遜認證

Springdoc-OpenAPI 基於我們的應用程序 REST API 生成文檔。此外，可以使用 Springdoc-OpenAPI 註釋自定義此文檔。

在本節中，讓我們學習為我們的 OpenAPI 配置基於 JWT 的身份驗證。

我們可以為每個操作、類或全局級別配置 OpenAPI 的 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 Authentication (Basic and Bearer) 、 OAuth2和OpenID Connect 。在這種情況下，讓我們使用HTTP Bearer Authentication作為我們的安全方案。

對於基於 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 ：

點擊 圖標打開一個登錄對話框，供用戶提供訪問令牌來調用操作：

對於此示例，可以通過向authentication API 提供john/password或jane/password來獲取 JWT 令牌.獲得 JWT 令牌後，我們可以將其傳遞到value文本框中，然後單擊Authorize按鈕，然後單擊Close按鈕：

有了 JWT 令牌，讓我們調用deleteUser API：

結果，我們看到該操作將提供一個 JWT 令牌，如 圖標，並且 Swagger-UI 在Authorization標頭中提供此令牌作為 HTTP Bearer。最後，有了這個配置，我們就可以成功調用受保護的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.全局配置

通常，我們更願意對應用程序中的所有 API 保留 OpenAPI 身份驗證。對於這些情況，我們可以使用 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 為應用程序中的所有 OpenAPI 配置 JWT 身份驗證：

讓我們嘗試調用 GET API：

最終，我們得到HTTP 401 Unauthorized. API 是安全的，我們沒有提供 JWT 令牌。接下來，讓我們提供 JWT 令牌並檢查行為。

單擊Authorize按鈕並提供 JWT 令牌以調用操作。我們可以從 swagger 控制台中可用的身份驗證 API 獲取不記名令牌：

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

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

4。結論

在本教程中，我們學習瞭如何為我們的 OpenAPI 配置 JWT 身份驗證。 Swagger-UI 提供了一個工具來記錄和測試基於 OneAPI 規範的 REST API。 Swaggerdoc-OpenAPI 工具幫助我們基於作為 Spring Boot 應用程序一部分的 REST API 生成此規範。

與往常一樣，完整的源代碼可在 GitHub 上獲得。