.NET 9 – Swashbuckle vs Scalar

V .NET 9 došlo ke změnám v podpoře pro dokumentaci API. Microsoft odstranil vestavěnou podporu pro Swagger (Swashbuckle) z důvodu nedostatečné údržby tohoto projektu a zaměřil se na integrovanou podporu OpenAPI prostřednictvím balíčku Microsoft.AspNetCore.OpenApi.

Pro interaktivní dokumentaci API nyní existuje alternativa nazvaná Scalar. Jedná se o open-source platformu, která poskytuje moderní a uživatelsky přívětivé rozhraní pro práci s OpenAPI/Swagger dokumenty.

Integrace Scalar do .NET 9 aplikace:

Instalace balíčku: Přidejte balíček Scalar.AspNetCore do svého projektu pomocí následujícího příkazu: add package Scalar.AspNetCore

Nastavení v aplikaci: V souboru Program.cs přidejte potřebné služby a mapování:

using Scalar.AspNetCore;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddOpenApi();

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();
    app.MapScalarApiReference();
}

app.MapGet("/", () => "Hello world!");

app.Run();


Tímto způsobem bude vaše API dokumentace dostupná na endpointu /scalar/v1

Přidání Bearer autentizace do Scalar:

Pokud vaše API využívá Bearer autentizaci, můžete ji integrovat do Scalar pomocí transformátoru:

Vytvořte třídu transformátoru:

public sealed class BearerSecuritySchemeTransformer(IAuthenticationSchemeProvider authenticationSchemeProvider) : IOpenApiDocumentTransformer
{
    public async Task TransformAsync(OpenApiDocument document, OpenApiDocumentTransformerContext context, CancellationToken cancellationToken)
    {
        var authenticationSchemes = await authenticationSchemeProvider.GetAllSchemesAsync();
        if (authenticationSchemes.Any(authScheme => authScheme.Name == "Bearer"))
        {
            var requirements = new Dictionary<string, OpenApiSecurityScheme>
            {
                ["Bearer"] = new OpenApiSecurityScheme
                {
                    Type = SecuritySchemeType.Http,
                    Scheme = "bearer",
                    In = ParameterLocation.Header,
                    BearerFormat = "JWT"
                }
            };
            document.Components ??= new OpenApiComponents();
            document.Components.SecuritySchemes = requirements;

            foreach (var operation in document.Paths.Values.SelectMany(path => path.Operations))
            {
                operation.Value.Security.Add(new OpenApiSecurityRequirement
                {
                    [new OpenApiSecurityScheme
                    {
                        Reference = new OpenApiReference
                        {
                            Id = "Bearer",
                            Type = ReferenceType.SecurityScheme
                        }
                    }] = Array.Empty<string>()
                });
            }
        }
    }
}

Registrujte transformátor ve službách:

builder.Services.AddOpenApi(opt =>
{
    opt.UseTransformer<BearerSecuritySchemeTransformer>();
});

Tímto způsobem zajistíte, že vaše API dokumentace bude správně reflektovat použití Bearer autentizace.

Více informací o Scalar a jeho integraci do .NET najdete v oficiální dokumentaci: Scalar Guides