如何使用 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

Answer 1

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

\n\n

\n\n

接口“IOperationProcessor”的实现：

\n\n

using NSwag;\nusing NSwag.SwaggerGeneration.Processors;\nusing NSwag.SwaggerGeneration.Processors.Contexts;\nusing System.Threading.Tasks;\n\nnamespace api.mstiDFE._Helpers.Swagger\n{\n    public class AddRequiredHeaderParameter : IOperationProcessor\n    {\n        public Task<bool> ProcessAsync(OperationProcessorContext context)\n        {\n            context.OperationDescription.Operation.Parameters.Add(\n            new SwaggerParameter\n            {\n                Name = "token",\n                Kind = SwaggerParameterKind.Header,\n                Type = NJsonSchema.JsonObjectType.String,\n                IsRequired = false,\n                Description = "Chave de acesso \xc3\xa0 API, fornecida pela RevendaCliente",\n                Default = "Default Value"\n            });\n\n            return Task.FromResult(true);\n        }\n    }\n}\n

\n\n

在startup.cs中参考：

\n\n

internal static void ConfigureServices(IServiceCollection services, IConfiguration configuration)\n{\n\n    // Register the Swagger services\n    services.AddSwaggerDocument(config =>\n    {\n        // Adds the "token" parameter in the request header, to authorize access to the APIs\n        config.OperationProcessors.Add(new AddRequiredHeaderParameter());\n\n        config.PostProcess = document =>\n        {\n            document.Info.Version = "v1";\n            document.Info.Title = "Title ";\n            document.Info.Description = "API para gera\xc3\xa7\xc3\xa3o de Documentos Fiscais Eletr\xc3\xb4nicos (DF-e) do projeto SPED";\n            document.Info.TermsOfService = "None";\n            document.Info.Contact = new NSwag.SwaggerContact\n            {\n                Name = "Name",\n                Email = "Email ",\n                Url = "Url "\n            };\n            document.Info.License = new NSwag.SwaggerLicense\n            {\n                Name = "Use under LICX",\n                Url = "https://example.com/license"\n            };\n\n        };\n    });            \n}\n

\n

Answer 2

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

尝试

Schema = new JsonSchema4 { Type = NJsonSchema.JsonObjectType.String }

代替

Type = NJsonSchema.JsonObjectType.String

（我认为 Type 在 OpenAPI 3 中已被弃用）

Answer 3

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

由于 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"
    });