Generare documenti OpenAPI

Il Microsoft.AspNetCore.OpenApi pacchetto fornisce il supporto predefinito per la generazione di documenti OpenAPI in ASP.NET Core. Il pacchetto offre le funzionalità seguenti:

• Supporto per la generazione di documenti OpenAPI in fase di esecuzione e l'accesso tramite un endpoint nell'app.
• Supporto per le API "transformer" che consentono di modificare il documento generato.
• Supporto per la generazione di più documenti OpenAPI da una singola app.
• Sfrutta il supporto dello schema JSON fornito da System.Text.Json.
• È compatibile con AoT nativo.

Installazione del pacchetto

Installare il pacchetto Microsoft.AspNetCore.OpenApi:

Visual Studio

Eseguire il comando seguente dalla console di Gestione pacchetti:

Install-Package Microsoft.AspNetCore.OpenApi

CLI .NET

Esegui questo comando:

dotnet add package Microsoft.AspNetCore.OpenApi

Configurare la generazione di documenti OpenAPI

Il codice seguente:

• Aggiunge servizi OpenAPI usando il metodo di estensione AddOpenApi nella raccolta di servizi del generatore di app.
• Esegue il mapping di un endpoint per visualizzare il documento OpenAPI in formato JSON con il metodo di estensione MapOpenApi nell'applicazione.

var builder = WebApplication.CreateBuilder();

builder.Services.AddOpenApi();

var app = builder.Build();

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

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

app.Run();

Avviare l'app e passare a https://localhost:<port>/openapi/v1.json per visualizzare il documento OpenAPI generato.

Opzioni per personalizzare la generazione di documenti OpenAPI

Le sezioni seguenti illustrano come personalizzare la generazione di documenti OpenAPI.

Personalizzare il nome del documento OpenAPI

Ogni documento OpenAPI in un'app ha un nome univoco. Il nome del documento predefinito registrato è v1.

builder.Services.AddOpenApi(); // Document name is v1

Il nome del documento può essere modificato passando il nome come parametro alla AddOpenApi chiamata.

builder.Services.AddOpenApi("internal"); // Document name is internal

Il nome del documento viene visualizzato in diverse posizioni nell'implementazione OpenAPI.

Quando si recupera il documento OpenAPI generato, il nome del documento viene fornito come argomento del documentName parametro nella richiesta. Le seguenti richieste trattano i documenti v1 e internal.

GET http://localhost:5000/openapi/v1.json
GET http://localhost:5000/openapi/internal.json

Personalizzare la versione OpenAPI di un documento generato

Per impostazione predefinita, la generazione di documenti OpenAPI crea un documento conforme alla versione 3.0 della specifica OpenAPI. Il codice seguente illustra come modificare la versione predefinita del documento OpenAPI:

builder.Services.AddOpenApi(options =>
{
    options.OpenApiVersion = OpenApiSpecVersion.OpenApi2_0;
});

Personalizzare la route dell'endpoint OpenAPI

Per impostazione predefinita, l'endpoint OpenAPI registrato tramite una chiamata a MapOpenApi espone il documento all'endpoint /openapi/{documentName}.json . Il codice seguente illustra come personalizzare la route in cui è registrato il documento OpenAPI:

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

È possibile, ma non consigliato, rimuovere il documentName parametro di route dalla route dell'endpoint. Quando il parametro di route documentName viene rimosso dalla route dell'endpoint, il framework tenta di determinare il nome del documento dal parametro di query. La mancata fornitura dell'elemento documentName nella route o nella query può causare effetti imprevisti.

Personalizzare l'endpoint OpenAPI

Poiché il documento OpenAPI viene fornito tramite un endpoint del gestore di route, qualsiasi personalizzazione disponibile per gli endpoint minimi standard è disponibile per l'endpoint OpenAPI.

Limitare l'accesso ai documenti OpenAPI agli utenti autorizzati

L'endpoint OpenAPI non abilita i controlli di autorizzazione per impostazione predefinita. Tuttavia, i controlli di autorizzazione possono essere applicati al documento OpenAPI. Nel codice seguente, l'accesso al documento OpenAPI è limitato a quelli con il tester ruolo :

using Microsoft.AspNetCore.Authentication;
using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.OpenApi;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.OpenApi.Models;

var builder = WebApplication.CreateBuilder();

builder.Services.AddAuthentication().AddJwtBearer();
builder.Services.AddAuthorization(o =>
{
    o.AddPolicy("ApiTesterPolicy", b => b.RequireRole("tester"));
});
builder.Services.AddOpenApi();

var app = builder.Build();

app.MapOpenApi()
    .RequireAuthorization("ApiTesterPolicy");

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

app.Run();

Documento OpenAPI generato nella cache

Il documento OpenAPI viene rigenerato ogni volta che viene inviata una richiesta all'endpoint OpenAPI. La rigenerazione consente ai trasformatori di incorporare lo stato dinamico dell'applicazione nel loro funzionamento. Ad esempio, rigenerando una richiesta con i dettagli del contesto HTTP. Se applicabile, il documento OpenAPI può essere memorizzato nella cache per evitare di eseguire la pipeline di generazione di documenti in ogni richiesta HTTP.

using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.OpenApi;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.OpenApi.Models;

var builder = WebApplication.CreateBuilder();

builder.Services.AddOutputCache(options =>
{
    options.AddBasePolicy(policy => policy.Expire(TimeSpan.FromMinutes(10)));
});
builder.Services.AddOpenApi();

var app = builder.Build();

app.UseOutputCache();

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

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

app.Run();

Generare più documenti OpenAPI

In alcuni scenari, è utile generare più documenti OpenAPI con contenuto diverso da un'unica app per le API core ASP.NET. Questi scenari sono:

• Generazione di documentazione OpenAPI per gruppi di destinatari diversi, ad esempio API pubbliche e interne.
• Generazione della documentazione openAPI per versioni diverse di un'API.
• Generazione della documentazione openAPI per diverse parti di un'app, ad esempio un front-end e un'API back-end.

Per generare più documenti OpenAPI, chiamare il metodo di estensione AddOpenApi una volta per ogni documento, specificando un nome di documento diverso nel primo parametro ogni volta.

builder.Services.AddOpenApi("v1");
builder.Services.AddOpenApi("v2");

Ogni chiamata di AddOpenApi può specificare il proprio set di opzioni, in modo da poter scegliere di usare le stesse personalizzazioni o diverse per ogni documento OpenAPI.

Il framework utilizza il metodo delegato ShouldInclude di OpenApiOptions per determinare quali endpoint includere negli documenti.

Per ogni documento, viene chiamato il metodo delegato ShouldInclude per ogni endpoint nell'app, passando l'oggetto ApiDescription per l'endpoint. Il metodo restituisce un valore booleano che indica se l'endpoint deve essere incluso nel documento. Oggetto ApiDescription:

• contiene informazioni sull'endpoint, ad esempio il metodo HTTP, la route e i tipi di risposta
• Metadati collegati all'endpoint tramite attributi o metodi di estensione.

L'implementazione predefinita di questo delegato usa il campo GroupName di ApiDescription. Il delegato viene impostato su un endpoint usando il metodo di estensione WithGroupName o l'attributo EndpointGroupNameAttribute. WithGroupName o l'attributo EndpointGroupName determina quali endpoint includere nel documento. Tutti gli endpoint a cui non è stato assegnato un nome di gruppo sono inclusi in tutti i documenti OpenAPI.

    // Include endpoints without a group name or with a group name that matches the document name
    ShouldInclude = (description) => description.GroupName == null || description.GroupName == DocumentName;    

È possibile personalizzare il metodo delegato ShouldInclude per includere o escludere gli endpoint in base a qualsiasi criterio scelto.

Generare documenti OpenAPI in fase di compilazione

Nelle app Web tipiche, i documenti OpenAPI vengono generati in fase di esecuzione e gestiti tramite una richiesta HTTP al server app.

In alcuni scenari, è utile generare il documento OpenAPI durante il passaggio di compilazione dell'app. Questi scenari sono:

• Generazione della documentazione OpenAPI che viene inserita nel controllo del codice sorgente.
• Generazione della documentazione openAPI usata per i test di integrazione basati su specifiche.
• Generazione della documentazione OpenAPI fornita in modo statico dal server Web.

Per aggiungere il supporto per la generazione di documenti OpenAPI in fase di compilazione, installare il Microsoft.Extensions.ApiDescription.Server pacchetto:

Visual Studio

Eseguire il comando seguente dalla console di Gestione pacchetti:

Install-Package Microsoft.Extensions.ApiDescription.Server

CLI .NET

Eseguire il comando seguente nella directory che contiene il file di progetto:

dotnet add package Microsoft.Extensions.ApiDescription.Server

Al momento dell'installazione, questo pacchetto:

• Genera automaticamente i documenti open API associati all'app durante la compilazione.
• Popola i documenti open API nella directory di output dell'app.

Se sono registrati più documenti, il nome del documento e è e nonv1, e viene post-fissato con il nome del documento. Ad esempio {ProjectName}_{DocumentName}.json.

Visual Studio Code

dotnet build
type obj\{ProjectName}.json

CLI di .NET Core

dotnet build
cat obj/{ProjectName}.json

Personalizzazione della generazione di documenti in fase di compilazione

Modifica della directory di output del file Open API generato

Per impostazione predefinita, il documento OpenAPI generato verrà generato nella directory di output dell'app. Per modificare il percorso del file generato, impostare il percorso di destinazione nella OpenApiDocumentsDirectory proprietà .

<PropertyGroup>
  <OpenApiDocumentsDirectory>.</OpenApiDocumentsDirectory>
</PropertyGroup>

Il valore di OpenApiDocumentsDirectory viene risolto in relazione al file di progetto. L'uso del . valore precedente genererà il documento OpenAPI nella stessa directory del file di progetto.

Modifica del nome del file di output

Per impostazione predefinita, il documento OpenAPI generato avrà lo stesso nome del file di progetto dell'app. Per modificare il nome del file generato, impostare l'argomento --file-name della proprietà OpenApiGenerateDocumentsOptions.

<PropertyGroup>
  <OpenApiGenerateDocumentsOptions>--file-name my-open-api</OpenApiGenerateDocumentsOptions>
</PropertyGroup>

Selezione del documento OpenAPI da generare

Alcune app possono essere configurate per generare più documenti OpenAPI. È possibile generare più documenti OpenAPI per versioni diverse di un'API o distinguere tra API pubbliche e interne. Per impostazione predefinita, il generatore di documenti in fase di compilazione genera file per tutti i documenti configurati in un'app. Per generare solo per un singolo nome di documento, impostare l'argomento --document-name nella proprietà OpenApiGenerateDocumentsOptions.

<PropertyGroup>
  <OpenApiGenerateDocumentsOptions>--document-name v2</OpenApiGenerateDocumentsOptions>
</PropertyGroup>

Personalizzazione del comportamento di runtime durante la generazione di documenti in fase di compilazione

Funzioni di generazione di documenti OpenAPI in fase di compilazione avviando il punto di ingresso dell'applicazione utilizzando un’implementazione simulata del server. È necessario un server fittizio per produrre documenti OpenAPI accurati perché tutte le informazioni nel documento OpenAPI non possono essere analizzate in modo statico. Poiché viene richiamato il punto di ingresso delle app, viene richiamata qualsiasi logica nell'avvio delle app. Questo include il codice che inserisce i servizi nel contenitore di DI o legge dalla configurazione. In alcuni scenari, è necessario limitare i percorsi di codice che verranno eseguiti quando il punto di ingresso delle app viene richiamato dalla generazione di documenti in fase di compilazione. Questi scenari sono:

• Non leggendo da determinate stringhe di configurazione.
• Non registra i servizi correlati al database.

Per impedire che questi percorsi di codice vengano richiamati dalla pipeline di generazione in fase di compilazione, possono essere condizionati dietro un controllo sull'assembly di ingresso.

using System.Reflection;

var builder = WebApplication.CreateBuilder(args);

if (Assembly.GetEntryAssembly()?.GetName().Name != "GetDocument.Insider")
{
    builder.AddServiceDefaults();
}

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error", createScopeForErrors: true);
    app.UseHsts();
}

var myKeyValue = app.Configuration["MyKey"];

app.MapGet("/", () => {
    return Results.Ok($"The value of MyKey is: {myKeyValue}");
})
.WithName("TestKey");

app.Run();

AddServiceDefaults aggiunge servizi di .NET Aspire comuni, ad esempio l'individuazione dei servizi, la resilienza, i controlli di integrità e OpenTelemetry.

Ottimizzazione e AOT nativo

OpenAPI in ASP.NET Core supporta il trimming e l'AOT nativo. La procedura seguente consente di creare e pubblicare un'app OpenAPI con ottimizzazione e AOT nativo.

Creare un nuovo progetto di ASP.NET Core Web API (Native AOT).

dotnet new webapiaot

Aggiungere il pacchetto Microsoft.AspNetCore.OpenAPI.

dotnet add package Microsoft.AspNetCore.OpenApi

Aggiornare Program.cs per abilitare la generazione di documenti OpenAPI.

+ builder.Services.AddOpenApi();

var app = builder.Build();

+ app.MapOpenApi();

Pubblicare l'app.

dotnet publish