Swagger UI 设置 JWT

教程

1、简介

本文将带你了解如何在 Spring Boot 中配置 Swagger UI，使其在调用 API 时包含 JWT（JSON Web Token）。

2、Maven 依赖

本例使用 springdoc-openapi-ui 库，它包含了使用 Swagger 和 Swagger UI 所需的所有依赖。

<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 Info 和 Security Scheme：

@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("salloszraj@gmail.com"))
            .license(new License().name("License of API")
                .url("API license URL")));
}

4、REST Controller

在 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。

你可以看到如下带有 Authorize 按钮的 Swagger 用户界面：

swaggerui

当点击 Authorize 按钮时，Swagger UI 会要求我们提供 JWT。

输入 Token，然后点击 Authorize，此时，向 API 发出的所有请求都将自动在 HTTP 头信息中包含 Token：

swagger authorize

6、带 JWT 的 API 请求

在向 API 发送请求时，可以看到 Authorization Header 带有设置 Token 值：

swagger 带有 Authorization Header 的请求

7、总结

本文介绍了如何在 Spring Boot 应用中通过 Swagger UI 提供的自定义配置来设置 JWT。

Ref：https://www.baeldung.com/spring-boot-swagger-jwt