Codebelt.Extensions.Swashbuckle.AspNetCore

Overview

Codebelt.Extensions.Swashbuckle.AspNetCore wraps the repetitive parts of Swashbuckle setup into a DI-oriented package for versioned ASP.NET Core APIs. AddRestfulSwagger captures OpenAPI metadata, XML documentation sources, and SwaggerGenOptions customizations in one RestfulSwaggerOptions object, then registers package-owned IConfigureOptions implementations for Swagger generation and Swagger UI.

Beyond registration, the package adds reusable building blocks for document filters, operation filters, XML comment discovery, and common OpenAPI security schemes. Functional tests show the package producing /swagger/v1/swagger.json output that picks up XML comments for controllers, minimal APIs, models, tokens, and ProblemDetails from both the app base directory and installed .NET reference packs.

Key APIs

AddRestfulSwagger(IServiceCollection, Action<RestfulSwaggerOptions>?) is the package entry point for wiring Swagger into an ASP.NET Core service collection. It copies the configured filter descriptors, schema settings, and security schemes from RestfulSwaggerOptions.Settings into Swashbuckle, registers package-owned Swagger generator and UI option configurators, and stores the resolved RestfulSwaggerOptions in DI.

RestfulSwaggerOptions is the package control surface for API metadata and document generation. It groups OpenApiInfo, XmlDocumentations, Settings, IncludeControllerXmlComments, and an optional JsonSerializerOptionsFactory into one validateable object so Swagger registration stays centralized instead of being spread across unrelated startup code.

DocumentFilter<T> and OperationFilter<T> give custom Swashbuckle filters a typed options object through IConfigurable<T>. Use these base classes when you want package or application filters to keep constructor-supplied configuration while still exposing the standard Swashbuckle Apply hooks.

AddUserAgent(SwaggerGenOptions, Action<UserAgentDocumentOptions>?) registers UserAgentDocumentFilter, which adds a reusable User-Agent header parameter to the OpenAPI components section and inserts that reference into every operation. UserAgentDocumentOptions lets you tune the header description, example, and required flag without authoring a custom filter from scratch.

AddJwtBearerSecurity, AddBasicAuthenticationSecurity, and AddXApiKeySecurity add matching OpenAPI security definitions and security requirements for common HTTP authentication styles. They are useful when Swagger UI should advertise the same Authorization or X-Api-Key headers your API expects, but you do not want to repeat the scheme definitions by hand in every service registration.

AddFromBaseDirectory, AddByType, AddByAssembly, and AddFromReferencePacks help populate RestfulSwaggerOptions.XmlDocumentations from XML files that live next to loaded assemblies or inside installed .NET reference packs. The owned tests show AddFromReferencePacks loading ProblemDetails documentation when packs are available and returning the original list unchanged in runtime-only environments where no packs directory exists.

Basic usage

using Codebelt.Extensions.Swashbuckle.AspNetCore;
using Codebelt.Extensions.Xunit;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Options;
using Xunit;

namespace MyProject.Tests;

public class RestfulSwaggerRegistrationTest : Test
{
    public RestfulSwaggerRegistrationTest(ITestOutputHelper output) : base(output)
    {
    }

    [Fact]
    public void ShouldCaptureSwaggerRegistrationSettings_WhenUsingRestfulSwagger()
    {
        var services = new ServiceCollection();

        services.AddRestfulSwagger(options =>
        {
            options.OpenApiInfo.Title = "Inventory API";
            options.Settings.AddUserAgent(userAgent =>
            {
                userAgent.Required = true;
                userAgent.Example = "Backoffice/2.3.0";
            });
            options.Settings.AddJwtBearerSecurity();
        });

        using var provider = services.BuildServiceProvider();
        var registered = provider.GetRequiredService<IOptions<RestfulSwaggerOptions>>().Value;

        TestOutput.WriteLine($"OpenAPI title: {registered.OpenApiInfo.Title}");
        TestOutput.WriteLine($"Document filters: {registered.Settings.DocumentFilterDescriptors.Count}");
        TestOutput.WriteLine($"Security schemes: {registered.Settings.SwaggerGeneratorOptions.SecuritySchemes.Count}");

        Assert.Equal("Inventory API", registered.OpenApiInfo.Title);
        Assert.Single(registered.Settings.DocumentFilterDescriptors);
        Assert.True(registered.Settings.SwaggerGeneratorOptions.SecuritySchemes.ContainsKey("Bearer"));
    }
}

This example keeps Swagger setup inside DI while still letting a test inspect the package-owned RestfulSwaggerOptions that will drive runtime generation. It is a practical pattern when you standardize Swagger registration across services and want AddUserAgent and AddJwtBearerSecurity to stay part of that shared contract.

Installation

dotnet add package Codebelt.Extensions.Swashbuckle.AspNetCore

Usage guidance

Use this package when an ASP.NET Core API already depends on Swashbuckle and you want version-aware Swagger registration, XML comment aggregation, or reusable security and header filters expressed as package-owned extensions instead of handwritten configuration. If you only need a single ad hoc Swagger customization with no shared RestfulSwaggerOptions setup or XML-document discovery, configuring Swashbuckle directly may be the smaller choice.

Family packages

package