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