Web API 使用 NSwag+Owin 为 Swagger 中的所有端点添加 Header 参数

Question

我希望在 Swagger 中为运行 ASP.NET 4.8 的 ASP.NET Web API 应用程序中的所有端点添加自定义标头参数。

我发现了很多很多解释如何在 .NET Core 中执行此操作的参考资料（.NET Core 流行示例），但在 .NET Framework 中却很少，而我找到的有关 .NET Framework 的参考资料（.NET Framework示例）与我的应用程序的配置方式不匹配。

当我的应用程序配置如下时，有没有办法添加自定义标头？ （这是我按照推荐 Owin 集成的包说明进行操作时获得的配置）。

RouteTable.Routes.MapOwinPath(
    "swagger",
    app =>
    {
        app.UseSwaggerUi(
            typeof(WebApiApplication).Assembly,
            settings =>
            {
                settings.MiddlewareBasePath = "/swagger";
                settings.GeneratorSettings.DefaultUrlTemplate =
                    "api/{controller}/{action}/{id}";
                settings.DocumentTitle = "My API";
                settings.GeneratorSettings.Title = "My API";
                settings.GeneratorSettings.Description = "My API"

            }
        );
    }
);

Answer 1

您可以通过配置 Swagger 生成器设置为所有端点添加自定义标头参数。

添加操作过滤器

using System.Web.Http.Description;
using NSwag.Generation.Processors;
using NSwag.Generation.Processors.Contexts;

public class AddCustomHeaderOperationFilter : IOperationProcessor
{
    public bool Process(OperationProcessorContext context)
    {
        // Add a custom header parameter
        context.OperationDescription.Operation.Parameters.Add(new NSwag.OpenApiParameter
        {
            Name = "X-Custom-Header",
            Kind = NSwag.OpenApiParameterKind.Header,
            Type = NJsonSchema.JsonObjectType.String,
            Description = "Custom header for all endpoints",
            IsRequired = false
        });

        return true;
    }
}

在您的配置中注册过滤器

修改您的 OWIN Swagger 配置以包含操作过滤器：

RouteTable.Routes.MapOwinPath(
    "swagger",
    app =>
    {
        app.UseSwaggerUi(
            typeof(WebApiApplication).Assembly,
            settings =>
            {
                settings.MiddlewareBasePath = "/swagger";
                settings.GeneratorSettings.DefaultUrlTemplate =
                    "api/{controller}/{action}/{id}";
                settings.DocumentTitle = "My API";
                settings.GeneratorSettings.Title = "My API";
                settings.GeneratorSettings.Description = "My API";

                // Add the custom header filter
                settings.GeneratorSettings.OperationProcessors.Add(new AddCustomHeaderOperationFilter());
            }
        );
    }
);

注意：您还可以通过在

IsRequired = true

实现中设置

AddCustomHeaderOperationFilter

来制作所需的标头。