如何为SpringBoot Swagger3的所有API添加必填请求头参数？

根据你使用的Swagger/OpenAPI版本，以下是几种可行的实现方式：

一、OpenAPI 3.x（YAML/JSON配置文件） #

OpenAPI 3.x支持直接在全局路径下定义参数，所有API会自动继承：

1. 先在components/parameters中定义必填请求头参数
2. 在paths根节点下添加parameters数组，引用这个全局参数

示例配置（YAML）：

openapi: 3.0.3
info:
  title: 业务API集合
  version: 1.0.0
components:
  parameters:
    X-Filter:
      name: X-Filter
      in: header
      required: true
      schema:
        type: string
        description: 用于筛选查询范围的必填请求头
paths:
  # 全局参数：所有路径下的API都会自动包含这个请求头
  parameters:
    - $ref: '#/components/parameters/X-Filter'
  /users:
    get:
      summary: 获取用户列表
      responses:
        '200':
          description: 返回用户列表数据
  /orders:
    get:
      summary: 获取订单列表
      responses:
        '200':
          description: 返回订单列表数据

如果个别API不需要这个参数，可以在对应接口的parameters中覆盖，比如设置required: false或者移除引用。

二、Swagger 2.0（旧版本YAML/JSON配置） #

Swagger 2.0没有全局路径参数的直接继承机制，可通过两种方式实现：

方式1：定义全局参数后逐个引用 #

先在根节点定义全局参数，然后在每个API的parameters中通过$ref引用：

swagger: '2.0'
info:
  title: 业务API集合
  version: 1.0.0
# 全局参数定义
parameters:
  X-Filter:
    name: X-Filter
    in: header
    required: true
    type: string
    description: 用于筛选查询范围的必填请求头
paths:
  /users:
    get:
      summary: 获取用户列表
      parameters:
        - $ref: '#/parameters/X-Filter'
      responses:
        200:
          description: 返回用户列表数据
  /orders:
    get:
      summary: 获取订单列表
      parameters:
        - $ref: '#/parameters/X-Filter'
      responses:
        200:
          description: 返回订单列表数据

方式2：批量脚本处理 #

如果API数量较多，可写简单脚本（比如Python/Node.js）遍历Swagger配置文件，自动给所有接口添加该参数引用，避免手动重复操作。

三、Spring Boot项目代码层面配置 #

如果你的Swagger文档是通过代码自动生成的，可通过框架注解或配置类实现全局参数：

1. Springdoc OpenAPI（适配OpenAPI 3.x） #

使用@OpenAPIDefinition注解全局添加参数：

import io.swagger.v3.oas.annotations.OpenAPIDefinition;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.enums.ParameterIn;
import io.swagger.v3.oas.annotations.info.Info;
import org.springframework.context.annotation.Configuration;

@Configuration
@OpenAPIDefinition(
        info = @Info(title = "业务API集合", version = "1.0.0"),
        parameters = {
                @Parameter(
                        name = "X-Filter",
                        in = ParameterIn.HEADER,
                        required = true,
                        description = "用于筛选查询范围的必填请求头"
                )
        }
)
public class OpenApiConfig {
}

2. Springfox Swagger2（适配Swagger 2.0） #

通过Docket配置全局操作参数：

import springfox.documentation.builders.ParameterBuilder;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.service.Parameter;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import java.util.Collections;
import java.util.List;

@Configuration
public class SwaggerConfig {
    @Bean
    public Docket api() {
        Parameter filterHeader = new ParameterBuilder()
                .name("X-Filter")
                .modelRef(new ModelRef("string"))
                .parameterType("header")
                .required(true)
                .description("用于筛选查询范围的必填请求头")
                .build();

        return new Docket(DocumentationType.SWAGGER_2)
                .globalOperationParameters(Collections.singletonList(filterHeader))
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.yourpackage.controller"))
                .paths(PathSelectors.any())
                .build();
    }
}

注意事项 #

• 务必同步更新后端接口逻辑，确保能正确接收并处理这个请求头参数，避免文档与实际接口行为不一致
• 通知所有API调用方该必填参数的存在及格式要求，避免集成报错
• 若部分API无需此参数，可在对应接口配置中单独覆盖参数的required属性为false

内容的提问来源于stack exchange，提问作者冯绍杰