如何在Swagger中为指定API端点选择性添加OperationFilter

实现方案 #

你可以通过「自定义特性+过滤器内判断」的方式实现按需添加认证头，步骤如下：

步骤1：创建自定义标记特性 #

先定义一个空的特性类，用来标记需要添加认证头的接口/控制器：

/// <summary>
/// 标记需要添加AccountName、ApiKey认证头的接口
/// </summary>
[AttributeUsage(AttributeTargets.Class | AttributeTargets.Method, AllowMultiple = false)]
public class RequireAuthHeadersAttribute : Attribute
{
}

步骤2：修改AuthenticationHeadersFilter逻辑 #

在过滤器的Apply方法中，先通过OperationFilterContext获取当前端点的元数据，判断是否打了上述自定义特性，没有则直接跳过添加头的逻辑：

public class AuthenticationHeadersFilter : IOperationFilter
{
    public void Apply(OpenApiOperation operation, OperationFilterContext context)
    {
        // 判断当前接口/所属控制器是否标记了RequireAuthHeadersAttribute
        var hasAuthAttribute = context.MethodInfo.DeclaringType.GetCustomAttributes(true)
            .Union(context.MethodInfo.GetCustomAttributes(true))
            .OfType<RequireAuthHeadersAttribute>()
            .Any();
        
        // 没有标记则直接返回，不添加认证头
        if (!hasAuthAttribute)
            return;

        if (operation.Parameters == null)
            operation.Parameters = new List<OpenApiParameter>();

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

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

步骤3：使用特性标记需要认证的端点 #

不需要修改原有Swagger注册逻辑，只需要在需要加认证头的控制器或者单个Action上打特性即可：

// 打在控制器上，控制器下所有接口都会添加认证头
[RequireAuthHeaders]
[ApiController]
[Route("api/[controller]")]
public class PrivateController : ControllerBase
{
    // 也可以只打在单个Action上，仅该接口添加认证头
    [RequireAuthHeaders]
    [HttpGet("test")]
    public IActionResult Test()
    {
        return Ok();
    }
}

// 没有打特性的公开控制器，所有接口都不会添加认证头
[ApiController]
[Route("api/public")]
public class PublicController : ControllerBase
{
    [HttpGet("demo")]
    public IActionResult Demo()
    {
        return Ok();
    }
}

可选：反向匹配逻辑 #

如果你的接口大部分需要认证，只有少数是公开接口，也可以反过来定义[PublicApi]特性，过滤器判断只要打了这个特性就跳过添加头，避免给大部分接口都打标记。

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