c# - 如何使用 C# .NET CORE 在 NSwag 文档中添加自定义标题？

Question

我需要添加自定义标题，但无法弄清楚。我正在尝试使用新的 services.AddOpenApiDocument() 而不是 services.AddSwaggerDocument()。我想在我的整个 API 上添加这些自定义标头，而不仅仅是单个方法或控制器。我试图添加一个操作处理器，但是当我加载 swagger UI 时，我收到以下错误“无法呈现此组件，请参阅控制台。”

这是我的片段ConfigureServices()：

    services.AddOpenApiDocument(document =>
    {
        ...
        // this works fine
        document.OperationProcessors.Add(new OperationSecurityScopeProcessor("Bearer"));
        document.DocumentProcessors.Add(new SecurityDefinitionAppender("Bearer", new SwaggerSecurityScheme
            {
                Type = SwaggerSecuritySchemeType.ApiKey,
                Name = "Authorization",
                In = SwaggerSecurityApiKeyLocation.Header
            })
        );

        // this is the header i want to show up for all endpoints that is breaking
        document.OperationProcessors.Add(new SampleHeaderOperationProcessor());
    });

这是我的操作处理器：

public class SampleHeaderOperationProcessor : IOperationProcessor
{
    public Task<bool> ProcessAsync(OperationProcessorContext context)
    {
        context.OperationDescription.Operation.Parameters.Add(
            new SwaggerParameter {
                Name = "Sample",
                Kind = SwaggerParameterKind.Header,
                Type = NJsonSchema.JsonObjectType.String,
                IsRequired = false,
                Description = "This is a test header",
                Default = "{{\"field1\": \"value1\", \"field2\": \"value2\"}}"
            });

        return Task.FromResult(true);
    }
}

我在我的 Configure() 中唯一与此有关的事情：

    app.UseSwagger();
    app.UseSwaggerUi3();

这是我的错误和控制台日志：我的错误和控制台日志

如果它有帮助我正在使用ASP .NET CORE 2.2和NSwag.AspNetCore v12.1.0

score 6 · Accepted Answer

这是我在项目中实现的一个示例。对我来说，它工作正常：

接口“IOOperationProcessor”的实现：

using NSwag;
using NSwag.SwaggerGeneration.Processors;
using NSwag.SwaggerGeneration.Processors.Contexts;
using System.Threading.Tasks;

namespace api.mstiDFE._Helpers.Swagger
{
    public class AddRequiredHeaderParameter : IOperationProcessor
    {
        public Task<bool> ProcessAsync(OperationProcessorContext context)
        {
            context.OperationDescription.Operation.Parameters.Add(
            new SwaggerParameter
            {
                Name = "token",
                Kind = SwaggerParameterKind.Header,
                Type = NJsonSchema.JsonObjectType.String,
                IsRequired = false,
                Description = "Chave de acesso à API, fornecida pela RevendaCliente",
                Default = "Default Value"
            });

            return Task.FromResult(true);
        }
    }
}

startup.cs 中的参考：

internal static void ConfigureServices(IServiceCollection services, IConfiguration configuration)
{

    // Register the Swagger services
    services.AddSwaggerDocument(config =>
    {
        // Adds the "token" parameter in the request header, to authorize access to the APIs
        config.OperationProcessors.Add(new AddRequiredHeaderParameter());

        config.PostProcess = document =>
        {
            document.Info.Version = "v1";
            document.Info.Title = "Title ";
            document.Info.Description = "API para geração de Documentos Fiscais Eletrônicos (DF-e) do projeto SPED";
            document.Info.TermsOfService = "None";
            document.Info.Contact = new NSwag.SwaggerContact
            {
                Name = "Name",
                Email = "Email ",
                Url = "Url "
            };
            document.Info.License = new NSwag.SwaggerLicense
            {
                Name = "Use under LICX",
                Url = "https://example.com/license"
            };

        };
    });            
}

score 5 · Accepted Answer

这终于对我有用。直接来自 Rico Suter 的解决方案，

尝试
Schema = new JsonSchema4 { Type = NJsonSchema.JsonObjectType.String }
代替
Type = NJsonSchema.JsonObjectType.String
（我认为 Type 在 OpenAPI 3 中已弃用）

score 4 · Accepted Answer

非常感谢这个线程上的原始答案。

由于 NSwag 更新，我不得不对上述答案进行一些小更新。

以下适用于我的版本（NSwag.Core：13.1.2，NJsonSchema：10.0.24）：

context.OperationDescription.Operation.Parameters.Add(
    new OpenApiParameter
    {
        Name = "HEADER_NAME",
        Kind = OpenApiParameterKind.Header,
        Schema = new JsonSchema { Type = JsonObjectType.String },
        IsRequired = true,
        Description = "Description",
        Default = "Default Value"
    });

c# - 如何使用 C# .NET CORE 在 NSwag 文档中添加自定义标题？

3 回答 3

Related

Reference