ASP.net Core - 在 Swagger 中评论特定版本

Question

我有一个存在版本 1 到 3 的 API。我正在创建一个特定控制器的 v4，我需要标题描述（见下文“负责...的 Api”）。

有没有办法对版本进行具体描述？我想在我的新 v4 中加入“草稿”一词。

我的启动配置如下...

服务集合

...

services.AddSwaggerGen(c =>
{
    services.BuildServiceProvider().GetRequiredService<IApiVersionDescriptionProvider>();

    var dir = new DirectoryInfo(AppDomain.CurrentDomain.BaseDirectory);
    foreach (var fi in dir.EnumerateFiles("*.xml"))
    {
        c.IncludeXmlComments(fi.FullName);
    }
    c.AddSecurityDefinition("Bearer",
        new OpenApiSecurityScheme
        {
            In = ParameterLocation.Header,
            Description = "Please insert JWT with Bearer into field",
            Name = "Authorization",
            Type = UseOpenApiV2 ? SecuritySchemeType.ApiKey : SecuritySchemeType.Http,
            Scheme = "bearer",
            BearerFormat = "JWT",
        });

    c.AddSecurityRequirement(new OpenApiSecurityRequirement
    {
            {
                new OpenApiSecurityScheme
                {
                    Reference = new OpenApiReference
                        {Type = ReferenceType.SecurityScheme, Id = "Bearer"},
                },
                new string[0]
            }
    });
    c.DocumentFilter<IncludeHostDocumentFilter>();
});
services.AddSwaggerGenNewtonsoftSupport();

...

配置

public void Configure(IApplicationBuilder app, IHostingEnvironment env, IApiVersionDescriptionProvider provider)
{
    if (!env.IsEnvironment("PROD"))
    {
        app.UseSwagger();
        app.UseSwaggerUI(o =>
        {
            foreach (var description in provider.ApiVersionDescriptions)
            {
                o.SwaggerEndpoint($"/swagger/{description.GroupName}/swagger.json", description.GroupName.ToUpperInvariant());
            }
            o.RoutePrefix = "swagger";
        });
    }

    app.UseCors("CorsPolicy");
    app.UseAuthentication();
    app.UseRequestResponseLogging();
    app.UseMvcWithDefaultRoute();
}

感谢您的指点！

Answer 1

您可以在 Swagger 文档中设置 Description 属性，如下所示：

c.SwaggerDoc("v4", 
         new OpenApiInfo 
         { 
            Version="v4",
            Title="v4 API",
            Description="DRAFT"
          });