Documentare un'API usando Swashbuckle
Swashbuckle è un pacchetto NuGet che consente di generare automaticamente documentazione Swagger per progetti API Web ASP.NET. Swagger è uno strumento che consente agli sviluppatori di progettare, compilare, documentare e utilizzare le API RESTful. Con Swashbuckle è possibile aggiungere facilmente la documentazione di Swagger al progetto API Web annotando il codice con attributi che descrivono gli endpoint, i parametri e le risposte dell'API. Swashbuckle usa quindi queste informazioni per generare un file JSON Swagger, che può essere usato per generare documentazione interattiva dell'API, SDK client e altro ancora.
Esistono tre componenti principali di Swashbuckle:
Swashbuckle.AspNetCore.Swagger: modello a oggetti Swagger e middleware per esporre gli oggetti SwaggerDocument come endpoint JSON.
Swashbuckle.AspNetCore.SwaggerGen: questa raccolta è un generatore Swagger che compila oggetti SwaggerDocument direttamente da route, controller e modelli. È usato in genere con il middleware di endpoint di Swagger per esporre automaticamente i file JSON di Swagger.
Swashbuckle.AspNetCore.SwaggerUI: una versione incorporata dello strumento interfaccia utente di Swagger, Interpreta i file JSON di Swagger per creare un'esperienza avanzata e personalizzabile per descrivere le funzionalità delle API Web. Include test harness predefiniti per i metodi pubblici.
Il comando dotnet add seguente installa il pacchetto NuGet Swashbuckle:
dotnet add <name>.csproj package Swashbuckle.AspNetCore -v 6.5.0
Aggiungere e configurare il middleware di Swagger
Aggiungere il generatore Swagger alla raccolta di servizi in Program.cs.
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();
Nota
La chiamata a AddEndpointsApiExplorer mostrata nell'esempio precedente è necessaria solo per le API minime.
Abilitare il middleware per la gestione del documento JSON generato e dell'interfaccia utente di Swagger, anche in Program.cs:
app.UseSwagger();
if (app.Environment.IsDevelopment())
{
app.UseSwaggerUI();
}
L'endpoint predefinito per l'interfaccia utente di Swagger è http:<hostname>:<port>/swagger.
Nota
SwaggerUI è molto utile nell'ambiente di sviluppo. Può essere abilitato nell'ambiente di produzione, ma è consigliabile esaminare eventuali requisiti di sicurezza per l'applicazione specifica prima di farlo.
Personalizzare ed estendere la documentazione di Swagger
Swagger offre opzioni per documentare il modello a oggetti e personalizzare l'interfaccia utente. L'azione di configurazione passata al metodo AddSwaggerGen può includere informazioni aggiuntive tramite la classe OpenApiInfo.
Nell'esempio di codice seguente viene illustrato come aggiungere informazioni da visualizzare nella documentazione dell'API.
// Add using statement for the OpenApiInfo class
using Microsoft.OpenApi.Models;
builder.Services.AddSwaggerGen(options =>
{
options.SwaggerDoc("v1", new OpenApiInfo
{
Version = "v1",
Title = "Fruit API",
Description = "API for managing a list of fruit their stock status.",
TermsOfService = new Uri("https://example.com/terms")
});
});
L'interfaccia utente di Swagger visualizza la versione e le informazioni aggiunte:
È possibile raggruppare le operazioni nell'API con l'opzione .WithTags. È anche possibile aggiungere testo descrittivo sull'operazione con l'opzione .WithSummary. Il codice di esempio seguente illustra l'uso di .WithTags per raggruppare l'operazione POST in un gruppo di post e in uno di frutta. Aggiunge anche il riepilogo specificato nell'opzione .WithSummary all'operazione.
app.MapPost("/fruits", async (Fruit fruit, FruitDb db) =>
{
db.Fruits.Add(fruit);
await db.SaveChangesAsync();
return Results.Created($"/{fruit.Id}", fruit);
})
.Produces<Fruit>(201)
.WithTags("post", "fruits")
.WithSummary("Create a new fruit");
L'interfaccia utente di Swagger visualizza il raggruppamento e la descrizione di riepilogo.
