TinyHelpers.AspNetCore.Swashbuckle 4.0.46

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.

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.AddSwaggerGen(options =>
{
    options.AddAcceptLanguageHeader();
    options.AddDefaultProblemDetailsResponse();
    options.AddTimeSpanTypeMapping(useCurrentTimeAsExample: true);
    options.AddOperationParameters();
});

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

Schema helpers

OpenApiSchemaHelper

This helper provides ready-to-use schema fragments that can be reused when building custom Swagger filters or other OpenAPI customizations.

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.AddSwaggerGen(options =>
{
    options.AddAcceptLanguageHeader();
    options.AddDefaultProblemDetailsResponse();
    options.AddTimeSpanTypeMapping("00:15:00");
    options.AddOperationParameters();
});

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

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.