在 Spring Boot 和 Swagger UI 中配置 JWT

1. 简介

在本篇文章中，我们将介绍如何配置 Swagger UI，使其在调用 API 时自动携带 JSON Web Token（JWT）。这对于调试和测试受保护的接口来说非常实用，尤其适合前后端分离或微服务架构下的开发流程。

Swagger UI 是一个功能强大的工具，它可以帮助我们快速测试 RESTful 接口，而 JWT 则是目前主流的身份认证方式之一。将两者结合使用，能显著提升开发效率。

2. Maven 依赖

在这个示例中，我们使用 springdoc-openapi-ui 来集成 Swagger 和 Swagger UI，它包含了所有必要的依赖项。我们需要将其添加到 pom.xml 文件中：

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

✅ 提示： springdoc 是目前 Spring Boot 项目中替代 springfox 的主流选择，性能更好、兼容性更强。

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")));
}

这段配置做了以下几件事：

✅ 定义了一个名为 Bearer Authentication 的安全方案
✅ 设置了 API 的标题、描述、版本、联系人等元信息
✅ 将该安全方案应用到整个 API 文档中

4. REST 控制器

接下来，我们在 ClientsRestController 中编写一个简单的接口用于测试：

@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");
    }
}

这个接口返回一个客户端列表，Swagger UI 会自动生成其文档页面，并允许我们进行测试。

5. Swagger UI 界面

启动应用后，我们可以通过以下地址访问 Swagger UI：

http://localhost:8080/swagger-ui.html

你会看到如下界面，注意右上角的 Authorize 按钮：

点击 Authorize 按钮后，会弹出一个对话框，要求输入 JWT Token：

输入格式应为：

Bearer <your-jwt-token>

⚠️ 注意：不要忘记 Bearer 前缀，否则请求头不会正确设置。

6. 带 JWT 的 API 请求

授权完成后，Swagger UI 会在后续所有请求中自动添加 Authorization 请求头，如下图所示：

✅ 这意味着你可以轻松地测试所有受保护的接口，而无需每次都手动设置 Token。

7. 总结

本文展示了如何在 Spring Boot 项目中使用 Swagger UI 配置 JWT 认证。通过简单的配置，我们可以在调试接口时自动携带 Token，从而更方便地测试受保护的资源。

这种方式非常适合开发阶段使用，避免了手动在 Postman 或 curl 中添加 Token 的繁琐操作。

源码地址：GitHub 仓库

Persistence

REST

Security