Un documento OpenAPI descrive le tue API in modo leggibile da persone e strumenti: client generati automaticamente, test, gateway, portali per sviluppatori. ASP.NET Core lo genera direttamente dal codice.

Configurazione minima

builder.Services.AddOpenApi();

var app = builder.Build();
app.MapOpenApi();          // /openapi/v1.json

In .NET 10 il documento segue la specifica OpenAPI 3.1, allineata a JSON Schema: tipi nullable e schemi descritti in modo più preciso.

Descrizioni dai commenti XML

Attivando la generazione della documentazione XML nel progetto, i commenti <summary> dei metodi e dei tipi diventano descrizioni nel documento OpenAPI.

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>

/// <summary>Restituisce un prodotto dato il suo codice.</summary>
/// <param name="codice">Codice articolo, per esempio ABC-123.</param>
static async Task<Results<Ok<Prodotto>, NotFound>> TrovaProdotto(string codice, ICatalogo catalogo) =>
    await catalogo.TrovaAsync(codice) is { } p ? TypedResults.Ok(p) : TypedResults.NotFound();

app.MapGet("/prodotti/{codice}", TrovaProdotto);

Anche in YAML

app.MapOpenApi("/openapi/{documentName}.yaml");

Esporlo in sicurezza

Il documento rivela la struttura delle API: in produzione valuta se pubblicarlo solo ad utenti autenticati o solo nell'ambiente di sviluppo. Per l'interfaccia grafica di consultazione si affiancano strumenti dedicati, come Scalar o Swagger UI.