Class UserAgentDocumentFilter

Namespace

Codebelt.Extensions.Swashbuckle.AspNetCore

Assembly

Codebelt.Extensions.Swashbuckle.AspNetCore.dll

Provides a User-Agent field to the generated OpenApiDocument.

public class UserAgentDocumentFilter : DocumentFilter<UserAgentDocumentOptions>, IDocumentFilter, IConfigurable<UserAgentDocumentOptions>

Inheritance

object

DocumentFilter

DocumentFilter<UserAgentDocumentOptions>

UserAgentDocumentFilter

Implements

IDocumentFilter

IConfigurable<UserAgentDocumentOptions>

Inherited Members

DocumentFilter<UserAgentDocumentOptions>.Options

Examples

Register UserAgentDocumentFilter with the Swagger generation pipeline to automatically document user-agent header requirements in the OpenAPI specification. This document filter is called during Swagger generation and modifies the specification to include the user-agent header as a required parameter on all API operations. You can register it directly as shown in the example, or use the convenient AddUserAgent() extension method for shorter setup code:

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 =>
        {
            // Register UserAgentDocumentFilter to document user-agent headers
            options.DocumentFilter<UserAgentDocumentFilter>();
            
            // Or use the convenient extension method
            // options.AddUserAgent();
        });

        var app = builder.Build();

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

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

Remarks

Inspiration for this class was borrowed from: https://github.com/tgstation/tgstation-server/blob/dev/src/Tgstation.Server.Host/Core/SwaggerConfiguration.cs

Constructors

UserAgentDocumentFilter(UserAgentDocumentOptions)

Initializes a new instance of the UserAgentDocumentFilter class.

public UserAgentDocumentFilter(UserAgentDocumentOptions options)

Parameters

options UserAgentDocumentOptions

The configured options of this instance.

Methods

Apply(OpenApiDocument, DocumentFilterContext)

Applies post-processing to the swaggerDoc.

public override void Apply(OpenApiDocument swaggerDoc, DocumentFilterContext context)

Parameters

swaggerDoc OpenApiDocument

The OpenApiDocument to modify.

context DocumentFilterContext

The DocumentFilterContext that provides additional context.

Remarks

Once an OpenApiDocument has been generated you have full control to modify the document however you see fit.

See Also

DocumentFilter<T>

UserAgentDocumentOptions