知識庫 / Spring / Spring Boot RSS 訂閱

1. 引言

在本簡短教程中，我們將學習如何配置 Swagger UI，以便在調用我們的 API 時包含 JSON Web Token (JWT)。

2. Maven 依賴

在本示例中，我們將使用 springdoc-openapi-ui，它包含了啓動與 Swagger 和 Swagger UI 協作所需的全部依賴項。 讓我們將其添加到我們的 <em >pom.xml</em> 文件中：

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

3. Swagger 配置

首先，我們需要配置 JWT SecurityScheme：

private SecurityScheme createAPIKeyScheme() {
    return new SecurityScheme().type(SecurityScheme.Type.HTTP)
        .bearerFormat("JWT")
        .scheme("bearer");
}

然後，我們配置OpenAPI Bean以包含API信息和安全方案。

@Bean
public OpenAPI openAPI() {
    return new OpenAPI().addSecurityItem(new SecurityRequirement().
            addList("Bearer Authentication"))
        .components(new Components().addSecuritySchemes
            ("Bearer Authentication", createAPIKeyScheme()))
        .info(new Info().title("My REST API")
            .description("Some custom description of API.")
            .version("1.0").contact(new Contact().name("Sallo Szrajbman")
                .email( "www.baeldung.com").url("[email protected]"))
            .license(new License().name("License of API")
                .url("API license URL")));
}

4. REST 控制器

在我們的 ClientsRestController 中，讓我們編寫一個簡單的 getClients 端點，以返回客户端列表：

@RestController(value = "/clients")
@Tag(name = "Clients")
public class ClientsRestController {

    @Operation(summary = "This method is used to get the clients.")
    @GetMapping
    public List<String> getClients() {
        return Arrays.asList("First Client", "Second Client");
    }
}

5. Swagger UI

當我們啓動應用程序時，可以通過 http://localhost:8080/swagger-ui.html URL 訪問 Swagger UI。

以下是 Swagger UI 的截圖，其中包含 Authorize 按鈕：

點擊 “Authorize” 按鈕後，Swagger UI 會提示輸入 JWT。

我們需要輸入我們的 token 並點擊 Authorize，之後所有對我們 API 的請求都會自動在 HTTP 頭部中包含 token：

6. 使用 JWT 發送 API 請求

當向我們的 API 發送請求時，您會注意到請求頭中包含一個“Authorization”標頭，其中包含您的 JWT 令牌值：

7. 結論

在本文中，我們瞭解到 Swagger UI 提供自定義配置，用於設置 JWT，這在處理應用程序的授權方面非常有用。 在 Swagger UI 中完成授權後，所有請求都會自動包含我們的 JWT。