Class SwaggerGenOptionsExtensions

Namespace

Codebelt.Extensions.Swashbuckle.AspNetCore

Assembly

Codebelt.Extensions.Swashbuckle.AspNetCore.dll

Extension methods for the SwaggerGenOptions class.

public static class SwaggerGenOptionsExtensions

Inheritance

object

SwaggerGenOptionsExtensions

Examples

Add security schemes and user-agent documentation to Swagger API specifications. These extension methods are called within the AddSwaggerGen(options => { ... }) setup action to document security mechanisms and required headers. The example shows how to compose multiple security scheme extensions together to document API Key, JWT Bearer, and Basic Authentication schemes, plus an additional user-agent header requirement. This declares the security options to the API consumer and generates the appropriate OpenAPI documentation:

using System;
using Codebelt.Extensions.Swashbuckle.AspNetCore;
using Microsoft.AspNetCore.Builder;
using Microsoft.Extensions.DependencyInjection;

namespace MySwaggerExample;

public class Program
{
    public static void Main(string[] args)
    {
        var builder = WebApplication.CreateBuilder(args);
        builder.Services.AddControllers();
        builder.Services.AddEndpointsApiExplorer();

        builder.Services.AddSwaggerGen(options =>
        {
            // Add security scheme documentation
            options.AddXApiKeySecurity();
            options.AddJwtBearerSecurity();
            options.AddBasicAuthenticationSecurity();
            
            // Add user-agent documentation
            options.AddUserAgent();
        });

        var app = builder.Build();
        if (string.Equals(app.Environment.EnvironmentName, "Development", StringComparison.OrdinalIgnoreCase))
        {
            app.UseSwagger();
            app.UseSwaggerUI();
        }

        app.MapControllers();
        app.Run();
    }
}

Methods

AddBasicAuthenticationSecurity(SwaggerGenOptions)

Adds support for AuthN/AuthZ using the Basic security scheme.

public static SwaggerGenOptions AddBasicAuthenticationSecurity(this SwaggerGenOptions options)

Parameters

options SwaggerGenOptions

The SwaggerGenOptions to extend.

Returns

SwaggerGenOptions

A reference to options so that additional calls can be chained.

Examples

Document HTTP Basic authentication:

using System;
using Codebelt.Extensions.Swashbuckle.AspNetCore;
using Microsoft.AspNetCore.Builder;
using Microsoft.Extensions.DependencyInjection;

namespace MySwaggerExample;

public class Program
{
    public static void Main(string[] args)
    {
        var builder = WebApplication.CreateBuilder(args);
        builder.Services.AddControllers();
        builder.Services.AddEndpointsApiExplorer();

        builder.Services.AddSwaggerGen(options =>
        {
            options.AddBasicAuthenticationSecurity();
        });

        var app = builder.Build();
        if (string.Equals(app.Environment.EnvironmentName, "Development", StringComparison.OrdinalIgnoreCase))
        {
            app.UseSwagger();
            app.UseSwaggerUI();
        }

        app.MapControllers();
        app.Run();
    }
}

AddJwtBearerSecurity(SwaggerGenOptions)

Adds support for AuthN/AuthZ using the Bearer security scheme in JWT format.

public static SwaggerGenOptions AddJwtBearerSecurity(this SwaggerGenOptions options)

Parameters

options SwaggerGenOptions

The SwaggerGenOptions to extend.

Returns

SwaggerGenOptions

A reference to options so that additional calls can be chained.

Examples

Document OAuth 2.0 Bearer token security scheme:

using System;
using Codebelt.Extensions.Swashbuckle.AspNetCore;
using Microsoft.AspNetCore.Builder;
using Microsoft.Extensions.DependencyInjection;

namespace MySwaggerExample;

public class Program
{
    public static void Main(string[] args)
    {
        var builder = WebApplication.CreateBuilder(args);
        builder.Services.AddControllers();
        builder.Services.AddEndpointsApiExplorer();

        builder.Services.AddSwaggerGen(options =>
        {
            options.AddJwtBearerSecurity();
        });

        var app = builder.Build();
        if (string.Equals(app.Environment.EnvironmentName, "Development", StringComparison.OrdinalIgnoreCase))
        {
            app.UseSwagger();
            app.UseSwaggerUI();
        }

        app.MapControllers();
        app.Run();
    }
}

AddUserAgent(SwaggerGenOptions, Action<UserAgentDocumentOptions>)

Adds an UserAgentDocumentFilter to the DocumentFilterDescriptors.

public static SwaggerGenOptions AddUserAgent(this SwaggerGenOptions options, Action<UserAgentDocumentOptions> setup = null)

Parameters

options SwaggerGenOptions

The SwaggerGenOptions to extend.

setup Action<UserAgentDocumentOptions>

The UserAgentDocumentOptions that may be configured.

Returns

SwaggerGenOptions

A reference to options so that additional calls can be chained.

AddXApiKeySecurity(SwaggerGenOptions)

Adds support for first line of defense using security based HTTP X-Api-Key header.

public static SwaggerGenOptions AddXApiKeySecurity(this SwaggerGenOptions options)

Parameters

options SwaggerGenOptions

The SwaggerGenOptions to extend.

Returns

SwaggerGenOptions

A reference to options so that additional calls can be chained.

Examples

Document API Key authentication using the standard X-API-Key header. Call this extension method within AddSwaggerGen to declare API Key as a supported security scheme in the OpenAPI specification. The extension automatically creates a security scheme definition and a global security requirement, so all endpoints automatically inherit this authentication requirement and the Swagger UI shows the key header as required:

using System;
using Codebelt.Extensions.Swashbuckle.AspNetCore;
using Microsoft.AspNetCore.Builder;
using Microsoft.Extensions.DependencyInjection;

namespace MySwaggerExample;

public class Program
{
    public static void Main(string[] args)
    {
        var builder = WebApplication.CreateBuilder(args);
        builder.Services.AddControllers();
        builder.Services.AddEndpointsApiExplorer();

        builder.Services.AddSwaggerGen(options =>
        {
            options.AddXApiKeySecurity();
        });

        var app = builder.Build();
        if (string.Equals(app.Environment.EnvironmentName, "Development", StringComparison.OrdinalIgnoreCase))
        {
            app.UseSwagger();
            app.UseSwaggerUI();
        }

        app.MapControllers();
        app.Run();
    }
}