TinyHelpers.AspNetCore.Swashbuckle 4.0.50

Tiny Helpers for Swashbuckle ASP.NET Core

TinyHelpers.AspNetCore.Swashbuckle is a small collection of practical helpers for Swashbuckle ASP.NET Core applications. It keeps common Swagger configuration in one place so applications can reuse the same OpenAPI conventions without duplicating setup code across startup files, endpoint metadata, or custom filters.

Compatibility

The package targets:

• .NET 8
• .NET 9
• .NET 10

It is designed to be used with Swashbuckle.AspNetCore and AddSwaggerGen(...).

Installation

Install the package from NuGet:

dotnet add package TinyHelpers.AspNetCore.Swashbuckle

Or search for TinyHelpers.AspNetCore.Swashbuckle in the Visual Studio Package Manager.

Contents

• Swagger and OpenAPI helpers
• Schema helpers
• Quick examples

Swagger and OpenAPI helpers

SwaggerExtensions

Example

using Microsoft.OpenApi;
using TinyHelpers.AspNetCore.Swagger;

builder.Services.AddSwaggerOperationParameters(parameters =>
{
    parameters.Parameters.Add(new OpenApiParameter
    {
        Name = "X-Correlation-Id",
        In = ParameterLocation.Header,
        Required = false,
        Description = "Identifier used to correlate requests"
    });
});

builder.Services.AddSwaggerGen(options =>
{
    options.AddAcceptLanguageHeader();
    options.AddDefaultProblemDetailsResponse();
    options.AddTimeSpanTypeMapping(useCurrentTimeAsExample: true);
    options.AddOperationParameters();
});

Register shared parameters with AddSwaggerOperationParameters() during service registration, then enable AddOperationParameters() in AddSwaggerGen(...). The options object stores the shared parameter definitions, and the operation filter copies them into generated operations. This prevents duplicated endpoint metadata while preserving a complete contract for Swagger UI and generated clients.

Schema helpers

OpenApiSchemaHelper

This helper provides ready-to-use schema fragments that can be reused when building custom Swagger filters or other OpenAPI customizations. It keeps default values, formats, and enum choices consistent across generated documents.

Example

using TinyHelpers.AspNetCore.Swagger;

var cultureSchema = OpenApiSchemaHelper.CreateSchema(["it-IT", "en-US"], "it-IT");
var durationSchema = OpenApiSchemaHelper.CreateStringSchema("00:30:00");

Example with an enum

public enum ExportFormat
{
    Csv,
    Json,
    Xml
}

var schema = OpenApiSchemaHelper.CreateSchema<ExportFormat>(ExportFormat.Json);

Quick examples

Minimal API with Swagger helpers

using Microsoft.OpenApi;
using Swashbuckle.AspNetCore.SwaggerGen;
using TinyHelpers.AspNetCore.Swagger;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddSwaggerOperationParameters(parameters =>
{
    parameters.Parameters.Add(new OpenApiParameter
    {
        Name = "X-Request-Id",
        In = ParameterLocation.Header,
        Required = false,
        Description = "Optional request correlation identifier"
    });
});

builder.Services.AddSwaggerGen(options =>
{
    options.AddAcceptLanguageHeader();
    options.AddDefaultProblemDetailsResponse();
    options.AddTimeSpanTypeMapping("00:15:00");
    options.AddOperationParameters();
});

var app = builder.Build();

app.UseSwagger();
app.UseSwaggerUI();

app.Run();

Building a reusable schema

using Microsoft.OpenApi;
using TinyHelpers.AspNetCore.Swagger;

var schema = OpenApiSchemaHelper.CreateSchema<string>(JsonSchemaType.String, "uuid");

Contribute

The project is continuously evolving. Contributions, issues, and pull requests are welcome.