C# 使用Swashbuckle Annotations定义响应头的可行性及替代方案问询

一、是否支持直接定义响应头 #

首先明确：Swashbuckle.AspNetCore.Annotations原生的[SwaggerResponse]特性本身不支持直接在参数里定义响应头，该特性仅支持设置响应状态码、描述、响应类型三个核心参数，没有预留响应头的配置入口。

二、可行的实现方案 #

以下是三种常用的实现方式：

方案1：自定义响应头特性配合OperationFilter（注解式适配方案） #

如果需要保持注解配置的使用习惯，可以自定义规则扩展功能：

1. 先定义用于标记响应头的特性类

[AttributeUsage(AttributeTargets.Method, AllowMultiple = true)]
public class SwaggerResponseHeaderAttribute : Attribute
{
    public int StatusCode { get; }
    public string HeaderName { get; }
    public string Description { get; }
    public Type Type { get; }

    public SwaggerResponseHeaderAttribute(int statusCode, string headerName, string description, Type type = null)
    {
        StatusCode = statusCode;
        HeaderName = headerName;
        Description = description;
        Type = type ?? typeof(string);
    }
}

2. 实现IOperationFilter扫描特性并生成Swagger响应头配置

public class ResponseHeaderOperationFilter : IOperationFilter
{
    public void Apply(OpenApiOperation operation, OperationFilterContext context)
    {
        var responseHeaders = context.MethodInfo
            .GetCustomAttributes(true)
            .OfType<SwaggerResponseHeaderAttribute>()
            .ToList();

        if (!responseHeaders.Any()) return;

        foreach (var header in responseHeaders)
        {
            if (operation.Responses.TryGetValue(header.StatusCode.ToString(), out var response))
            {
                response.Headers ??= new Dictionary<string, OpenApiHeader>();
                response.Headers.Add(header.HeaderName, new OpenApiHeader
                {
                    Description = header.Description,
                    Schema = OpenApiSchemaFactory.CreateSchema(header.Type)
                });
            }
        }
    }
}

3. 在Swagger配置中注册过滤器

builder.Services.AddSwaggerGen(c =>
{
    c.OperationFilter<ResponseHeaderOperationFilter>();
});

4. 直接在接口上使用即可

[HttpGet]
[SwaggerResponse(200, "OK", typeof(SampleResponseClass))]
[SwaggerResponseHeader(200, "X-Total-Count", "总数据条数", typeof(int))]
[SwaggerResponseHeader(200, "X-Request-ID", "请求唯一标识")]
public IActionResult GetSampleData()
{
    // 业务逻辑
}

方案2：OperationFilter全局批量配置 #

如果响应头是项目统一规范，比如所有接口都返回X-Request-ID，可以直接在过滤器中批量添加，无需额外加注解：

public class GlobalResponseHeaderFilter : IOperationFilter
{
    public void Apply(OpenApiOperation operation, OperationFilterContext context)
    {
        foreach (var response in operation.Responses.Values)
        {
            response.Headers ??= new Dictionary<string, OpenApiHeader>();
            response.Headers.Add("X-Request-ID", new OpenApiHeader
            {
                Description = "请求唯一追踪ID",
                Schema = new OpenApiSchema { Type = "string" }
            });
        }
    }
}

同样需要在Swagger配置中注册该过滤器。

方案3：原生[ProducesResponseHeader]特性（.NET 7+ 支持） #

如果你使用.NET 7及以上版本，且Swashbuckle版本≥6.4.0，可以直接用ASP.NET Core官方提供的[ProducesResponseHeader]特性，Swashbuckle已经原生支持识别该特性，不需要额外写过滤器：

[HttpGet]
[SwaggerResponse(200, "OK", typeof(SampleResponseClass))]
[ProducesResponseHeader("X-Total-Count", StatusCodes.Status200OK, Type = typeof(int), Description = "总数据条数")]
public IActionResult GetSampleData()
{
    // 业务逻辑
}

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