如何在ASP.NET Core Web API的Swashbuckle中添加自定义请求头？

我之前刚好处理过一模一样的需求，给你几个实用的方案，帮你把orgid、brnid这类自定义请求头加到Swagger文档里，还能支持调试时直接输入：

如果你的所有API接口都需要这两个自定义头，用这个方法最省心。我们可以写一个操作过滤器，让Swagger自动给所有接口加上这两个请求头配置。

在你的Program.cs（.NET 6+）或者Startup.cs里，找到AddSwaggerGen的配置代码，添加如下内容：

builder.Services.AddSwaggerGen(c =>
{
    // 保留你原来的JWT认证配置
    c.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme
    {
        Name = "Authorization",
        Type = SecuritySchemeType.Http,
        Scheme = "Bearer",
        BearerFormat = "JWT",
        In = ParameterLocation.Header,
        Description = "JWT授权头格式：Bearer {token}"
    });

    // 注册自定义操作过滤器
    c.OperationFilter<CustomHeaderOperationFilter>();
});

// 自定义操作过滤器类
public class CustomHeaderOperationFilter : IOperationFilter
{
    public void Apply(OpenApiOperation operation, OperationFilterContext context)
    {
        // 初始化参数列表（防止null）
        if (operation.Parameters == null)
            operation.Parameters = new List<OpenApiParameter>();

        // 添加orgid请求头
        operation.Parameters.Add(new OpenApiParameter
        {
            Name = "orgid",
            In = ParameterLocation.Header,
            Required = true, // 设为true表示必填，可选则改为false
            Schema = new OpenApiSchema
            {
                Type = "string",
                Default = new OpenApiString("fe5mp0") // 设置默认值，方便调试
            },
            Description = "组织ID，用于请求验证"
        });

        // 添加brnid请求头
        operation.Parameters.Add(new OpenApiParameter
        {
            Name = "brnid",
            In = ParameterLocation.Header,
            Required = true,
            Schema = new OpenApiSchema
            {
                Type = "string",
                Default = new OpenApiString("NY0023")
            },
            Description = "分支ID，用于请求验证"
        });
    }
}

配置完之后，启动项目打开Swagger页面，所有接口的调试区域都会自动出现这两个请求头的输入框，默认值已经填好，直接就能测试。

如果不是所有接口都需要这两个头，我们可以用自定义注解的方式，灵活控制哪些接口需要添加。

第一步：定义自定义注解 #

先写一个Attribute类，用来标记需要自定义头的接口：

[AttributeUsage(AttributeTargets.Method | AttributeTargets.Class, Inherited = false)]
public class RequiredCustomHeadersAttribute : Attribute
{
    public string[] Headers { get; }

    // 支持传入多个头名称
    public RequiredCustomHeadersAttribute(params string[] headers)
    {
        Headers = headers;
    }
}

第二步：修改操作过滤器 #

让过滤器识别这个注解，只给标记过的接口添加请求头：

public class CustomHeaderOperationFilter : IOperationFilter
{
    public void Apply(OpenApiOperation operation, OperationFilterContext context)
    {
        // 先检查方法上有没有注解，没有就检查控制器上的
        var requiredHeaders = context.MethodInfo.GetCustomAttribute<RequiredCustomHeadersAttribute>()
                             ?? context.MethodInfo.DeclaringType?.GetCustomAttribute<RequiredCustomHeadersAttribute>();

        // 如果没有标记，直接返回
        if (requiredHeaders == null || requiredHeaders.Headers.Length == 0)
            return;

        if (operation.Parameters == null)
            operation.Parameters = new List<OpenApiParameter>();

        foreach (var headerName in requiredHeaders.Headers)
        {
            // 根据头名称设置默认值和描述
            var defaultValue = headerName switch
            {
                "orgid" => "fe5mp0",
                "brnid" => "NY0023",
                _ => null
            };

            var description = headerName switch
            {
                "orgid" => "组织ID",
                "brnid" => "分支ID",
                _ => "自定义验证头"
            };

            operation.Parameters.Add(new OpenApiParameter
            {
                Name = headerName,
                In = ParameterLocation.Header,
                Required = true,
                Schema = new OpenApiSchema
                {
                    Type = "string",
                    Default = defaultValue != null ? new OpenApiString(defaultValue) : null
                },
                Description = description
            });
        }
    }
}

第三步：标记需要的接口/控制器 #

在控制器或者单个接口方法上添加注解即可：

// 整个控制器的所有接口都需要这两个头
[ApiController]
[Route("api/orders")]
[RequiredCustomHeaders("orgid", "brnid")]
public class OrdersController : ControllerBase
{
    // 单个方法只需要orgid
    [HttpGet("{id}")]
    [RequiredCustomHeaders("orgid")]
    public IActionResult GetOrder(int id)
    {
        // 业务逻辑
        return Ok();
    }
}

Swagger里显示了请求头只是方便调试，真正的验证逻辑还需要你自己实现。比如可以写一个Action过滤器，在请求到达接口之前读取并验证orgid和brnid的合法性：

public class CustomHeaderValidationFilter : IActionFilter
{
    public void OnActionExecuting(ActionExecutingContext context)
    {
        if (!context.HttpContext.Request.Headers.TryGetValue("orgid", out var orgid) || orgid != "fe5mp0")
        {
            context.Result = new UnauthorizedObjectResult("无效的orgid");
            return;
        }

        if (!context.HttpContext.Request.Headers.TryGetValue("brnid", out var brnid) || brnid != "NY0023")
        {
            context.Result = new UnauthorizedObjectResult("无效的brnid");
            return;
        }
    }

    public void OnActionExecuted(ActionExecutedContext context)
    {
        // 无需处理
    }
}

然后在Program.cs里注册这个过滤器：

builder.Services.AddControllers(options =>
{
    options.Filters.Add<CustomHeaderValidationFilter>();
});

内容的提问来源于stack exchange，提问作者Nitesh Shaw