在 Swagger for ASP .NET Core 3.1 中为标头添加过滤器

Question

我遵循了这个：

Web Api 如何在 Swagger 中为所有 API 添加 Header 参数

和这个：

如何在 Swagger UI 中发送带有请求的自定义标头？

但是，这些 IParameter、Parameter 或 NonBodyParameters 均不适用于 ASP .NET CORE 3.1。

我想在我的 swagger 上添加一个标题，它采用最好从登录用户那里获取的租户 ID。

我也经历过这个：

https://github.com/domaindrivendev/Swashbuckle.AspNetCore

任何人都可以指出我正确的方向吗？

using Swashbuckle.AspNetCore.Swagger;
using Swashbuckle.AspNetCore.SwaggerGen;
using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using System.Collections.Generic;
using Microsoft.AspNetCore.Mvc.ApiExplorer;
using Microsoft.AspNetCore.JsonPatch.Operations;
using Microsoft.OpenApi.Models;

namespace Intent2.Auth.Utils
{
    public class AddRequiredHeaderParameter : IOperationFilter
    {
        public void Apply(OpenApiOperation operation, OperationFilterContext context)
        {
            
            if (operation.Parameters == null)
                operation.Parameters = new List<IParameter>();

            operation.Parameters.Add(new NonBodyParameter
            {
                Name = "X-User-Token",
                In = "header",
                Type = "string",
                Required = false
            });
        }
    }
}
services.AddSwaggerGen(options =>
{
    options.OperationFilter<AddRequiredHeaderParameter>();
}

Answer 1

在与 ASP.NET Core 3.1 兼容的最新版本的 Swashbuckle 中，许多类型已被Microsoft.OpenApi.Models命名空间中的等效类型替换。 所以你不应该再使用像NonBodyParameter或IParameter这样的类型。 这两个都已被单个类OpenApiParameter取代。

你的代码应该是这样的

using Microsoft.OpenApi.Any;
using Microsoft.OpenApi.Models;
using Swashbuckle.AspNetCore.SwaggerGen;
using System.Collections.Generic;

namespace Intent2.Auth.Utils
{
    public class AddRequiredHeaderParameter : IOperationFilter
    {
        public void Apply(OpenApiOperation operation, OperationFilterContext context)
        {

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

            operation.Parameters.Add(new OpenApiParameter()
            {
                Name = "X-User-Token",
                Description = "Access Token",
                In = ParameterLocation.Header,
                Schema = new OpenApiSchema() { Type = "String" },
                Required = true,
                Example = new OpenApiString("Tenant ID example")
            });
        }
    }
}

然后在你的启动中，像往常一样简单地注入 SwaggerGen

services.AddSwaggerGen(options =>
{
    options.OperationFilter<AddRequiredHeaderParameter>();
}

例如，您甚至可以使租户 ID 像配置文件一样来自外部。 为此，请按如下方式修改您的AddRequiredHeaderParameter

using Microsoft.OpenApi.Any;
using Microsoft.OpenApi.Models;
using Swashbuckle.AspNetCore.SwaggerGen;
using System;
using System.Collections.Generic;

namespace Intent2.Auth.Utils
{
    public class AddRequiredHeaderParameter : IOperationFilter
    {
        private string _tenantIdExample;

        public AddRequiredHeaderParameter(string tenantIdExample)
        {
            if (string.IsNullOrEmpty(tenantIdExample )) 
                throw new ArgumentNullException(nameof(tenantIdExample ));

            _tenantIdExample = tenantIdExample;
        }

        public void Apply(OpenApiOperation operation, OperationFilterContext context)
        {

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

            operation.Parameters.Add(new OpenApiParameter()
            {
                Name = "X-User-Token",
                Description = "Access Token",
                In = ParameterLocation.Header,
                Schema = new OpenApiSchema() { Type = "String" },
                Required = true,
                Example = new OpenApiString(_tenantIdExample)
            });
        }
    }
}

从你的初创公司就这样称呼它

services.AddSwaggerGen(options =>
{
    options.OperationFilter<AddRequiredHeaderParameter>("Tenant ID example");
}

顺便说一句，我认为如果你的类被称为AddRequiredHeaderParameter你实际上应该设置Required = true而不是false