.net-core - .NET Core 2.0 Web API - 如何在 Swagger 中添加自定义 header 参数

Question

根据标题 - 我找到了如何使用常规 .NET 执行此操作的示例

例如: Web Api How to add a Header parameter for all API in Swagger

但是，我找不到任何示例或文档来说明如何在使用 .NET Core 2.0 时完成同样的事情。

Answer 1

swagger/OpenApi 请求 header 和响应 header 中有两种类型的 header 。

请求 header

请求 header 很容易实现，您所需要做的就是像这样装饰 Controller 和/或操作:

[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 will automatically pick up any headers defined with FromHeaderAttribute and apply it to the swagger document.

响应 header

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

下面的示例将返回自定义 header 名称 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 包含响应 header 。这是通过 IOperationFilter 完成的，请参阅 Swashbuckle documentation关于过滤器的工作原理。过滤器可以全局应用或按操作应用，但是您无法通过将参数传递到其构造函数来自定义行为，而是按照声明过滤器的方式(仅按类型)进行操作。因此，您必须为每个 API 方法编写一个操作过滤器，以返回一个或多个响应 header 。或者，您可以定义一个属性来声明操作的响应 header 。

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; }
}

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

    [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>();
};

我希望这足以让您继续前进。