ASP.NET Core 在 Swagger UI 中顯示自定義的 Header Token

Swagger 是個好東西，對於前后端分離的網站來說，不僅是提高前后端開發人員溝通效率的利器，也大大方便了后端人員測試 API。有時候，API 中可能需要在 Header 中設置認證參數，比如 authToken，這樣的功能我們通常是使用 ActionFilter 實現的，這就會導致 swagger UI 中缺少 authToken 字段，下面就來介紹解決這個問題的辦法。

創建一個過濾器類，內容如下：

/// <summary>
/// this class is for swagger to generate AuthToken Header filed on swagger UI
/// </summary>
public class AddAuthTokenHeaderParameter : IOperationFilter
{
    public void Apply(Operation operation, OperationFilterContext context)
    {
        if (operation.Parameters == null)
            operation.Parameters = new List<IParameter>();
        var attrs = context.ApiDescription.GetActionAttributes();
        foreach (var attr in attrs)
        {
            // 如果 Attribute 是我們自定義的驗證過濾器
            if (attr.GetType() == typeof(Auth))
            {
                operation.Parameters.Add(new NonBodyParameter()
                {
                    Name = "AuthToken",
                    In = "header",
                    Type = "string",
                    Required = false
                });
            }
        }
    }
}

然后在配置 Swagger 的地方，做一些修改：

services.AddSwaggerGen(c =>
            {
                c.SingleApiVersion(new Info()
                {
                    Version = "v1",
                    Title = "API 文檔",
                    Description = "系統的 API 文檔"
                });
                c.OperationFilter<AddAuthTokenHeaderParameter>(); // 手動高亮
            });

最后，dotnet run！

這樣，Swagger UI 中就顯示了附加在 header 中的參數——AuthToken，還要啥 Postman。