.Net Core 5.x Api开发笔记 -- Swagger设置Header(九)

Swagger的基础使用可以参考之前的文章：.Net Core 5.x Api开发笔记 -- Swagger(七)

这里只记录如何给Swagger添加Header，要达到的效果如下图所示：

1，添加 HttpHeaderFilter 参数设置类

在项目中添加一个参数设置类，命名自定义就行，如下图所示：

代码如下：

public class HttpHeaderFilter : IOperationFilter
{
    /// <summary>
    /// 给Swagger添加Header头部参数
    /// </summary>
    /// <param name="operation"></param>
    /// <param name="context"></param>
    public void Apply(OpenApiOperation operation, OperationFilterContext context)
    {
        operation.Parameters = new List<OpenApiParameter>
        {
            new OpenApiParameter
            {
                Name = "token",
                Description = "Token",
                In = ParameterLocation.Header,
                Required = false
            },
            new OpenApiParameter
            {
                Name = "TermID",
                Description = "学期ID",
                In = ParameterLocation.Header,
                Required = false
            },
            new OpenApiParameter
            {
                Name = "ContainerID",
                Description = "组织ID",
                In = ParameterLocation.Header,
                Required = false
            }
        };
    }
}

参数说明：

Name：就是设置header的字段属性名称，在同一个参数位置，名称必须唯一，且大小写敏感。

In：参数位置，常见有三个：

• path：参数成为操作路径（URL）的一部分，俗称路径参数。路径参数的 required 字段必需为 true
• query：参数成为操作路径（URL）查询参数的一部分，俗称查询参数，如/users?id=123456
• header：参数成为 HTTP 请求头的一部分，俗称请求头参数。注意：请求头是大小写敏感的

Required：是否必需，默认值是 false

我们按照 In：参数位置的类型分别设置成 Header、Query、Path，看是什么效果

 

2, 使用参数设置类 HttpHeaderFilter 

上边的参数类已经创建好，下边看下如何使用、使用很简单，代码如下(加红标粗的代码部分)

public void ConfigureServices(IServiceCollection services)
{
    services.AddControllers();

    //swagger
    services.AddSwaggerGen(options =>
    {
        options.SwaggerDoc("swaggerapi", new OpenApiInfo
        {
            Version = "v1",
            Title = "swaggerapi API文档",
            Description = "swaggerapi API的使用说明"
        });

        // 为 Swagger JSON and UI设置xml文档注释路径
        // 获取应用程序所在目录（绝对路径，不受工作目录影响，建议采用此方法获取路径）
        // 此方式适用于Windows/Linux 平台
        var basePath = Path.GetDirectoryName(typeof(Program).Assembly.Location);
        var xmlPath = Path.Combine(basePath, "NetCore.Swagger.xml");
        options.IncludeXmlComments(xmlPath);

        //添加自定义header授权参数
        options.OperationFilter<HttpHeaderFilter>(Array.Empty<object>());
    });
}

完毕！！！