请求标头

请求标题很容易实现，您需要做的就是装饰您的控制器和/或操作，如下所示：

[Route("api/[controller]")]
public class RequestHeadersController : Controller
{
    [FromHeader(Name = "x-my-controller-wide-header")]
    public string MyControllerWideHeader { get; set; }

    [HttpGet]
    public string Get([FromHeader(Name = "x-my-operation-header")]string myOperationHeader)
    {
        return myOperationHeader;
    }
}

Swashbuckle.AspNetCore 会自动选取使用FromHeaderAttribute定义的所有标头，并将其应用于招摇文档。

响应标头

在Asp.Net Core或Swashbuckle中没有指定响应头的声明方式，因此您必须手动执行此操作。

下面的示例将返回自定义标题名称x-my-header。

[Route("api/[controller]")]
public class ResponseHeadersController : Controller
{
    [HttpGet]
    public string Get()
    {
        HttpContext.Response.Headers["x-my-header"] = "header value";

        return "value";
    }
}

我们现在需要指示swagger包含响应头。这是通过IOperationFilter完成的，有关过滤器的工作原理，请参阅Swashbuckle documentation。过滤器可以全局或按操作应用，但是您无法通过将参数传递到其构造函数来自定义行为，而是按照声明过滤器的方式（仅按类型）。因此，您必须为每个返回一个或多个响应标头的API方法编写一个操作过滤器。或者，您可以定义一个属性来声明操作的响应头。

public enum HeaderResponseType { String, Number }

[AttributeUsage(AttributeTargets.Method, AllowMultiple = true, Inherited = true)]
public class ProducesResponseHeaderAttribute : Attribute
{
    public ProducesResponseHeaderAttribute(string name, int statusCode)
    {
        Name = name ?? throw new ArgumentNullException(nameof(name));
        StatusCode = statusCode;
        Type = HeaderResponseType.String;
    }

    public string Name { get; set; }
    public int StatusCode { get; set; }
    public HeaderResponseType Type { get; set; }
    public string Description { get; set; }
}

这使我们能够为每个响应代码声明一个或多个标题。

    [HttpGet]
    [ProducesResponseHeader("x-my-header", (int)HttpStatusCode.OK)]
    public string Get()
    {
        HttpContext.Response.Headers["x-my-header"] = "header value";

        return "string";
    }

现在我们有了一个定义我们意图的属性，我们可以制作一个通用的操作过滤器。

public class ResponseHeadersFilter : IOperationFilter
{
    public void Apply(Operation operation, OperationFilterContext context)
    {
        // Get all response header declarations for a given operation
        var actionResponsesWithHeaders = context.ApiDescription.ActionAttributes()
            .OfType<ProducesResponseHeaderAttribute>()
            .ToArray();

        if (!actionResponsesWithHeaders.Any())
            return;

        foreach (var responseCode in operation.Responses.Keys)
        {
            // Do we have one or more headers for the specific response code
            var responseHeaders = actionResponsesWithHeaders.Where(resp => resp.StatusCode.ToString() == responseCode);
            if (!responseHeaders.Any())
                continue;

            var response = operation.Responses[responseCode];
            if (response.Headers == null)
                response.Headers = new Dictionary<string, Header>();

            foreach (var responseHeader in responseHeaders)
            {
                response.Headers[responseHeader.Name] = new Header
                {
                    Type = responseHeader.Type.ToString(),
                    Description = responseHeader.Description
                };
            }
        }
    }
}

我们现在需要做的就是将操作过滤器连接到swagger生成。

// Startup.cs
services.AddSwaggerGen(c =>
{
    ...
    c.OperationFilter<ResponseHeadersFilter>();
};

我希望这足以让你前进。

.NET Core 2.0 Web API - 如何在Swagger中添加自定义标头参数

1 个答案:

请求标头

响应标头