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

Question

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

例如: Web Api如何为Swagger中的所有API添加Header参数

但是,我找不到任何示例或文档,显示如何在使用.NET Core 2.0时完成相同的操作.

Answer 1

swagger/OpenApi请求标头和响应标头中有两种类型的标头.

请求标题

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

[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并将其应用于swagger文档.

响应标题

在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文档,了解过滤器的工作原理.可以全局或按操作应用过滤器,但是您无法通过将参数传递到其构造函数来自定义行为,而是按照声明过滤器的方式(仅按类型).因此,您必须为每个返回一个或多个响应标头的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>();
};

我希望这足以让你前进.