ASP.NET Core Swagger Open API 如何给Controller级增加参数

我们知道我们可以给 ASP.NET 的 controller 的每个方法增加参数，这样在 Swagger 页面我们就可以设置好参数，然后进行测试，但是有些参数我们会要求它出现在每个公开的 controller 方法中。我们固然可以给每个方法都增加一个参数设置，但是这样做会增加我们很多工作量。

比如在下面的 TicketController 中，我们希望给每个方法都加一个 siteId 类型的 header 参数，来指名这个方法是发给哪个 site 的。一种方法是给 Purchase 和 Print 方法各增加一个 siteId 参数说明，这样在以后新增的方法中，我们都需要这么做。

[Route("tickets")]
[ApiController]
public class TicketsController : ControllerBase
{
	  /// <summary>
      /// Create a purchase ticket request
      /// </summary>
      /// <returns></returns>      
      [HttpPost("purchase")]
      public async Task<IActionResult> Purchase([FromBody] TicketPurchaseRequest request)
      {
      }
	  /// <summary>
      /// Print ticket
      /// </summary>
      /// <returns></returns>      
      [HttpPost("print")]
      public async Task<IActionResult> Print([FromBody] TicketPrintRequest request)
      {
      }
}

更好的方法是增加一个类实现 IOperationFilter 接口。代码如下：

public class SiteIdHeaderParameter : IOperationFilter
{
    public void Apply(OpenApiOperation operation, OperationFilterContext context)
    {
        if (operation.Parameters == null)
        {
            operation.Parameters = new List<OpenApiParameter>();
        }

        operation.Parameters.Add(new OpenApiParameter
        {
            Name = "SiteId",
            In = ParameterLocation.Header,
            Required = false
        });
    }
}

然后在 asp.net 的 StartUp.ConfigureService 方法中的swagger配置中引用它。参考代码如下：

_ = services.AddSwaggerGen(c =>
{
    c.OperationFilter<SiteIdHeaderParameter>();
    // Other configuration ...
}

这样我们就可以在 Swagger 页面的每个方法中看到 siteId 这个参数了

参考资料：
https://stackoverflow.com/questions/41493130/web-api-how-to-add-a-header-parameter-for-all-api-in-swagger