使用Springdoc-OpenAPI集成JWT认证的OpenAPI文档实践

Swagger-UI

Swagger-UI 是一套基于 HTML、JavaScript 和 CSS 的工具，能根据 OpenAPI 规范自动生成可视化界面。我们直接使用 Springdoc-OpenAPI 库来自动生成 REST API 的 OpenAPI 文档，并通过 Swagger-UI 直观地测试这些接口。

当应用中的 API 数量激增时，手动编写 OpenAPI 规范文档会变得非常繁琐。Springdoc-OpenAPI 帮我们解决了这个痛点，能自动生成文档。下面我们就来实际操作一下。

2.1. 依赖配置

简单粗暴，直接添加 Springdoc-OpenAPI 依赖：

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

这个依赖会自动将 Swagger-UI 的 web-jars 包集成到 Spring Boot 应用中。

2.2. 基础配置

启动应用后，在浏览器访问 http://localhost:8080/swagger-ui.html，就能看到 Swagger-UI 界面：

同时，OpenAPI v3.0 规范文档可通过 http://localhost:8080/v3/api-docs 直接获取。

如果需要补充 API 描述、服务条款等元信息，使用 @OpenAPIDefinition 注解：

@Configuration
@OpenAPIDefinition(
  info =@Info(
    title = "用户 API",
    version = "${api.version}",
    contact = @Contact(
      name = "技术团队", email = "tech@example.com", url = "https://example.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 = "生产环境"
  )
)
public class OpenAPISecurityConfiguration {}

建议将配置项外置到 application.properties 或 application.yaml 中管理（如 api.version、tos.uri 等）。

2.3. 效果验证

启动应用，访问 http://localhost:8080/swagger-ui/index.html 查看配置后的 Swagger-UI：

对应的 OpenAPI 文档（http://localhost:8080/v3/api-docs）会返回类似以下结构：

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

JWT 认证集成

Springdoc-OpenAPI 能基于应用中的 REST API 自动生成文档，同时支持通过注解自定义文档内容。本节重点说明如何为 OpenAPI 配置 JWT 认证。

认证配置支持三个级别：

单个操作级别
控制器类级别
全局应用级别

3.1. 操作级配置

先从最细粒度的单个接口开始配置。定义全局安全方案：

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

@SecurityScheme 注解会将安全方案添加到 OpenAPI 规范的 components 部分。支持的安全方案包括：APIKey、HTTP 认证（Basic/Bearer）、OAuth2 和 OpenID Connect。这里我们选用 HTTP Bearer 认证。

关键配置点：

安全方案类型设为 bearerAuth
Bearer 格式明确为 JWT

然后对需要保护的接口添加 @SecurityRequirement 注解：

@Operation(summary = "删除用户", description = "删除用户操作")
@SecurityRequirement(name = "Bearer 认证")
@DeleteMapping
public String deleteUser(Authentication authentication) {
    // 实现逻辑
}

重启应用后访问 Swagger-UI，会看到接口旁出现锁图标：

点击锁图标弹出认证对话框：

实际操作步骤：

获取 JWT Token（通过认证接口，使用 john/password 或 jane/password）
将 Token 填入输入框
点击 Authorize → Close

现在调用 deleteUser 接口，请求头会自动携带 Authorization: Bearer <token>：

⚠️ 踩坑提醒：确保 Token 格式正确，避免前缀多余空格（如 Bearer token 而非 Bearer token）

3.2. 类级配置

若整个控制器都需要认证，直接在类上添加 @SecurityRequirement：

@RequestMapping("/api/user")
@RestController
@SecurityRequirement(name = "bearerAuth")
@Tag(name = "用户管理", description = "用户相关操作接口集合")
public class UserApi {
    // 所有接口自动应用认证
}

效果：类内所有接口显示锁图标

3.3. 全局配置

当应用中所有接口都需要认证时，推荐全局配置。通过 @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")));
    }
}

全局生效后，Swagger-UI 界面所有接口都会显示锁图标：

测试流程：

未认证时调用接口返回 HTTP 401
通过认证接口获取 Token
授权后成功调用

💡 最佳实践：生产环境建议结合 Spring Security 实现真正的认证逻辑，OpenAPI 仅用于文档展示

总结

本文演示了在 Spring Boot 应用中通过 Springdoc-OpenAPI 集成 JWT 认证的完整流程。核心要点：

Swagger-UI 提供了基于 OpenAPI 规范的可视化文档与测试能力
Springdoc-OpenAPI 自动生成文档，避免手动维护的繁琐
JWT 认证 支持三级配置：
- 操作级：精确控制单个接口
- 类级：批量保护控制器
- 全局级：统一应用认证策略

完整源码可在 GitHub 获取。

Persistence

REST

Security