Swashbuckle ASP.NET Core Setup

Swagger is a great tool for documenting APIs. This article will show you how to set it up with ASP.NET Core.

Getting Started

Swashbuckle.AspNetCore is a nuget package, which includes some Swagger tools for documenting APIs built on ASP.NET Core. Install the latest version to your API project.

Setup the dependency injection:

public void ConfigureServices(IServiceCollection services)
{
    // ...
    services.AddSwaggerGen(c =>
    {
        c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });
    });
}

Use the middlewares:

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    // ...
    app.UseSwagger();

    app.UseSwaggerUI(c =>
    {
        c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
    });
    // ...
}

Swagger UI is now ready to use.

XML Comments

XML Comments are a special kind of comment to document the program. Swagger can be configured to include the documentation.

public void ConfigureServices(IServiceCollection services)
{
    services.AddControllers();

    services.AddSwaggerGen(c =>
    {
        c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });

        var filePath = Path.Combine(AppContext.BaseDirectory, "SwaggerSample.xml");
        c.IncludeXmlComments(filePath);
    });
}

Make sure the project file is configured to generate the XML file.

Bearer Security Definition

Most APIs use bearer authentication header to protect the endpoints. We can configure Swagger to ask for a bearer authentication header. Refer to this blog.

public void ConfigureServices(IServiceCollection services)
{
    services.AddControllers();

    services.AddSwaggerGen(c =>
    {
        c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });

        c.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme
        {
            Name = "Authorization",
            Type = SecuritySchemeType.ApiKey,
            Scheme = "Bearer",
            BearerFormat = "JWT",
            In = ParameterLocation.Header,
            Description = "JWT Authorization header using the Bearer scheme."
        });

        c.AddSecurityRequirement(new OpenApiSecurityRequirement
        {
            {
                new OpenApiSecurityScheme
                {
                    Reference = new OpenApiReference
                    {
                        Type = ReferenceType.SecurityScheme,
                        Id = "Bearer"
                    }
                }, 
                new string[] {}
            }
        });

        var filePath = Path.Combine(AppContext.BaseDirectory, "SwaggerSample.xml");
        c.IncludeXmlComments(filePath);
    });
}

Unauthorized Response

For protected endpoints, we can use Operation Filter to add a 401 status code.

/// <summary>
/// This operation filter adds unauthorized response.
/// </summary>
public class UnauthorizedResponseOperationFilter : IOperationFilter
{
    /// <inheritdoc />
    public void Apply(OpenApiOperation operation, OperationFilterContext context)
    {
        if (context.MethodInfo.DeclaringType == null)
        {
            return;
        }

        var authorizeAttributes = context.MethodInfo.DeclaringType.GetCustomAttributes(true)
            .Union(context.MethodInfo.GetCustomAttributes(true))
            .OfType<AuthorizeAttribute>();

        if (authorizeAttributes.Any())
            operation.Responses.Add(((int)HttpStatusCode.Unauthorized).ToString(), new OpenApiResponse { Description = HttpStatusCode.Unauthorized.ToString() });
    }
}

Then add it to the configuration:

c.OperationFilter<UnauthorizedResponseOperationFilter>();

Similarly we can add 403 and 501 status codes.