ASP.net Core - comment specific versions in Swagger

Question

I have an API with versions 1 to 3 that exists. I am creating a v4 of a particular controller and I need the heading description (see below as "Api in charge of ...").

Is there a way to have a specific description for a version? I want to put the word "DRAFT" into my new v4.

My startup is configured as follows...

ServiceCollection

...

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();

...

Configure

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();
}

Thanks for any pointers!

Answer 1

You could set the Description property in Swagger document like below:

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