SpringDoc OpenAPI 中如何配置全局请求头

在基于Spring Boot和SpringDoc OpenAPI的项目中，我们经常需要为所有API接口配置统一的请求头参数。本文将详细介绍如何在SpringDoc OpenAPI中配置全局请求头，确保该参数在Swagger UI中始终可见且会被自动提交。

配置方法

SpringDoc OpenAPI提供了简洁的配置方式来实现全局请求头的设置。以下是一个完整的配置示例：

@Bean
public OpenAPI springDocOpenAPI() {
    OpenAPI api = new OpenAPI();
    
    // 配置安全方案（请求头参数）
    api.components(new Components().addSecuritySchemes("x-token", 
        new SecurityScheme()
            .type(SecurityScheme.Type.APIKEY)
            .in(SecurityScheme.In.HEADER)
            .name("x-token")
            .description("用户Token")));
    
    // 配置API基本信息
    api.info(new Info()
            .title("Service APIs")
            .description("系统业务接口服务")
            .version("3.0.0"));
    
    // 将安全方案应用到所有接口
    api.addSecurityItem(new SecurityRequirement().addList("x-token"));
    
    return api;
}

配置详解

1. 安全方案配置：

   • 使用SecurityScheme类定义请求头参数
   • type设置为APIKEY表示这是一个API密钥类型的参数
   • in设置为HEADER表示参数位于请求头中
   • name指定请求头的名称
   • description提供参数的描述信息

2. 全局应用：

   • 通过addSecurityItem方法将定义的安全方案应用到所有接口
   • 这会确保该请求头参数在Swagger UI中显示为必填项

注意事项

1. 参数名称（如示例中的"x-token"）需要与实际API要求的请求头名称完全一致
2. 这种配置方式适用于SpringDoc OpenAPI 2.x版本
3. 配置完成后，Swagger UI会自动在每个接口的请求中携带该请求头

与Swagger2的对比

相比于传统的Swagger2配置方式，SpringDoc OpenAPI的配置更加简洁直观。在Swagger2中，我们需要创建一个SecurityScheme列表，而在SpringDoc中，我们可以直接在OpenAPI对象中进行配置。

通过以上配置，开发者可以轻松地为所有API接口添加统一的请求头参数，简化了API文档的维护工作，同时也提高了API测试的便利性。