Condividi tramite

Generare documenti OpenAPI

  • Articolo

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'applicazione.
  • 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:

Eseguire il comando seguente dalla console di Gestione pacchetti:

Install-Package Microsoft.AspNetCore.OpenApi

Configurare la generazione di documenti OpenAPI

Il codice seguente:

  • Aggiunge servizi OpenAPI.
  • Abilita l'endpoint per la visualizzazione del documento OpenAPI in formato JSON.
var builder = WebApplication.CreateBuilder();

builder.Services.AddOpenApi();

var app = builder.Build();

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 richieste seguenti risolvono i v1 documenti 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 documentName parametro di route viene rimosso dalla route dell'endpoint, il framework tenta di risolvere il nome del documento dal parametro di query. La mancata fornitura documentName di nella route o nella query può comportare un comportamento imprevisto.

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 dell'applicazione dinamica 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();

app.MapOpenApi()
    .CacheOutput();

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

app.Run();

Generare documenti OpenAPI in fase di compilazione

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

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

  • Generazione della documentazione OpenAPI di cui viene eseguito il commit 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:

Eseguire il comando seguente dalla console di Gestione pacchetti:

Install-Package Microsoft.Extensions.ApiDescription.Server

Al momento dell'installazione, questo pacchetto genererà automaticamente i documenti open API associati all'applicazione durante la compilazione e li popola nella directory di output dell'applicazione.

$ dotnet build
$ cat bin/Debug/net9.0/{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'applicazione. 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'applicazione. Per modificare il nome del file generato, impostare l'argomento --file-name nella OpenApiGenerateDocumentsOptions proprietà .

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

Selezione del documento OpenAPI da generare

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

<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 condizionali dietro un controllo dell'assembly di immissione:

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 --prerelease

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

+ builder.Services.AddOpenApi();

var app = builder.Build();

+ app.MapOpenApi();

Pubblicare l'app.

dotnet publish

Le API minime offrono il supporto predefinito per la generazione di informazioni sugli endpoint in un'app tramite il Microsoft.AspNetCore.OpenApi pacchetto. L'esposizione della definizione OpenAPI generata tramite un'interfaccia utente visiva richiede un pacchetto di terze parti. Per informazioni sul supporto per OpenAPI nelle API basate su controller, vedere la versione .NET 9 di questo articolo.

Il codice seguente viene generato dal modello api Web minimo di ASP.NET core e usa OpenAPI:

using Microsoft.AspNetCore.OpenApi;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

app.UseHttpsRedirection();

var summaries = new[]
{
    "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
};

app.MapGet("/weatherforecast", () =>
{
    var forecast = Enumerable.Range(1, 5).Select(index =>
        new WeatherForecast
        (
            DateTime.Now.AddDays(index),
            Random.Shared.Next(-20, 55),
            summaries[Random.Shared.Next(summaries.Length)]
        ))
        .ToArray();
    return forecast;
})
.WithName("GetWeatherForecast")
.WithOpenApi();

app.Run();

internal record WeatherForecast(DateTime Date, int TemperatureC, string? Summary)
{
    public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);
}

Nel codice evidenziato precedente:

  • Microsoft.AspNetCore.OpenApi viene spiegato nella sezione successiva.
  • AddEndpointsApiExplorer : configura l'app per l'uso di Esplora API per individuare e descrivere gli endpoint con annotazioni predefinite. WithOpenApi esegue l'override delle annotazioni predefinite generate da Esplora API con quelle generate dal Microsoft.AspNetCore.OpenApi pacchetto.
  • UseSwaggeraggiunge il middleware Swagger.
  • 'UseSwaggerUI' abilita una versione incorporata dello strumento dell'interfaccia utente di Swagger.
  • WithName IEndpointNameMetadata: nell'endpoint viene usato per la generazione di collegamenti e viene considerato come l'ID operazione nella specifica OpenAPI dell'endpoint specificato.
  • WithOpenApi viene spiegato più avanti in questo articolo.

pacchetto NuGet Microsoft.AspNetCore.OpenApi

ASP.NET Core fornisce il Microsoft.AspNetCore.OpenApi pacchetto per interagire con le specifiche OpenAPI per gli endpoint. Il pacchetto funge da collegamento tra i modelli OpenAPI definiti nel Microsoft.AspNetCore.OpenApi pacchetto e gli endpoint definiti nelle API minime. Il pacchetto fornisce un'API che esamina i parametri, le risposte e i metadati di un endpoint per costruire un tipo di annotazione OpenAPI usato per descrivere un endpoint.

Microsoft.AspNetCore.OpenApi viene aggiunto come PackageReference a un file di progetto:

<Project Sdk="Microsoft.NET.Sdk.Web">

  <PropertyGroup>
    <TargetFramework>net7.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
  </PropertyGroup>

  <ItemGroup>    
    <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="7.0.*-*" />
    <PackageReference Include="Swashbuckle.AspNetCore" Version="6.4.0" />
  </ItemGroup>

</Project>

Quando si usa Swashbuckle.AspNetCore con Microsoft.AspNetCore.OpenApi, è necessario usare la Swashbuckle.AspNetCore versione 6.4.0 o successiva. Microsoft.OpenApi 1.4.3 o versione successiva deve essere usato per sfruttare i costruttori di copia nelle WithOpenApi chiamate.

Aggiungere annotazioni OpenAPI agli endpoint tramite WithOpenApi

La chiamata WithOpenApi all'endpoint aggiunge ai metadati dell'endpoint. Questi metadati possono essere:

  • Utilizzato in pacchetti di terze parti come Swashbuckle.AspNetCore.
  • Visualizzato nell'interfaccia utente di Swagger o in YAML o JSON generato per definire l'API.
app.MapPost("/todoitems/{id}", async (int id, Todo todo, TodoDb db) =>
{
    todo.Id = id;
    db.Todos.Add(todo);
    await db.SaveChangesAsync();

    return Results.Created($"/todoitems/{todo.Id}", todo);
})
.WithOpenApi();

Modificare l'annotazione OpenAPI in WithOpenApi

Il WithOpenApi metodo accetta una funzione che può essere usata per modificare l'annotazione OpenAPI. Nel codice seguente, ad esempio, viene aggiunta una descrizione al primo parametro dell'endpoint:

app.MapPost("/todo2/{id}", async (int id, Todo todo, TodoDb db) =>
{
    todo.Id = id;
    db.Todos.Add(todo);
    await db.SaveChangesAsync();

    return Results.Created($"/todoitems/{todo.Id}", todo);
})
.WithOpenApi(generatedOperation =>
{
    var parameter = generatedOperation.Parameters[0];
    parameter.Description = "The ID associated with the created Todo";
    return generatedOperation;
});

Aggiungere ID operazione a OpenAPI

Gli ID operazione vengono usati per identificare in modo univoco un determinato endpoint in OpenAPI. Il WithName metodo di estensione può essere usato per impostare l'ID operazione utilizzato per un metodo.

app.MapGet("/todoitems2", async (TodoDb db) =>
    await db.Todos.ToListAsync())
    .WithName("GetToDoItems");

In alternativa, la OperationId proprietà può essere impostata direttamente nell'annotazione OpenAPI.

app.MapGet("/todos", async (TodoDb db) => await db.Todos.ToListAsync())
    .WithOpenApi(operation => new(operation)
    {
        OperationId = "GetTodos"
    });

Aggiungere tag alla descrizione OpenAPI

OpenAPI supporta l'uso di oggetti tag per classificare le operazioni. Questi tag vengono in genere usati per raggruppare le operazioni nell'interfaccia utente di Swagger. Questi tag possono essere aggiunti a un'operazione richiamando il metodo di estensione WithTags nell'endpoint con i tag desiderati.

app.MapGet("/todoitems", async (TodoDb db) =>
    await db.Todos.ToListAsync())
    .WithTags("TodoGroup");

In alternativa, l'elenco di OpenApiTags può essere impostato nell'annotazione OpenAPI tramite il WithOpenApi metodo di estensione.

app.MapGet("/todos", async (TodoDb db) => await db.Todos.ToListAsync())
    .WithOpenApi(operation => new(operation)
    {
        Tags = new List<OpenApiTag> { new() { Name = "Todos" } }
    });

Aggiungere il riepilogo o la descrizione dell'endpoint

Il riepilogo e la descrizione dell'endpoint possono essere aggiunti richiamando il WithOpenApi metodo di estensione. Nel codice seguente i riepiloghi vengono impostati direttamente nell'annotazione OpenAPI.

app.MapGet("/todoitems2", async (TodoDb db) => await db.Todos.ToListAsync())
    .WithOpenApi(operation => new(operation)
    {
        Summary = "This is a summary",
        Description = "This is a description"
    });

Escludere la descrizione OpenAPI

Nell'esempio seguente l'endpoint /skipme viene escluso dalla generazione di una descrizione OpenAPI:

using Microsoft.AspNetCore.OpenApi;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

app.UseHttpsRedirection();

app.MapGet("/swag", () => "Hello Swagger!")
    .WithOpenApi();
app.MapGet("/skipme", () => "Skipping Swagger.")
                    .ExcludeFromDescription();

app.Run();

Contrassegnare un'API come obsoleta

Per contrassegnare un endpoint come obsoleto, impostare la proprietà nell'annotazione Deprecated OpenAPI.

app.MapGet("/todos", async (TodoDb db) => await db.Todos.ToListAsync())
    .WithOpenApi(operation => new(operation)
    {
        Deprecated = true
    });

Descrivere i tipi di risposta

OpenAPI supporta la descrizione delle risposte restituite da un'API. Le API minime supportano tre strategie per impostare il tipo di risposta di un endpoint:

Il Produces metodo di estensione può essere usato per aggiungere Produces metadati a un endpoint. Quando non vengono forniti parametri, il metodo di estensione popola i metadati per il tipo di destinazione con un 200 codice di stato e un application/json tipo di contenuto.

app
    .MapGet("/todos", async (TodoDb db) => await db.Todos.ToListAsync())
    .Produces<IList<Todo>>();

L'uso TypedResults nell'implementazione del gestore di route di un endpoint include automaticamente i metadati del tipo di risposta per l'endpoint. Ad esempio, il codice seguente annota automaticamente l'endpoint con una risposta nel 200 codice di stato con un application/json tipo di contenuto.

app.MapGet("/todos", async (TodoDb db) =>
{
    var todos = await db.Todos.ToListAsync());
    return TypedResults.Ok(todos);
});

Impostare le risposte per ProblemDetails

Quando si imposta il tipo di risposta per gli endpoint che possono restituire una risposta ProblemDetails, il ProducesProblem metodo di estensione, ProducesValidationProblemo è TypedResults.Problem possibile usare per aggiungere l'annotazione appropriata ai metadati dell'endpoint. Si noti che i ProducesProblem metodi di estensione e ProducesValidationProblem non possono essere usati con i gruppi di route in .NET 8 e versioni precedenti.

Quando non sono presenti annotazioni esplicite fornite da una delle strategie precedenti, il framework tenta di determinare un tipo di risposta predefinito esaminando la firma della risposta. Questa risposta predefinita viene popolata sotto il 200 codice di stato nella definizione OpenAPI.

Più tipi di risposta

Se un endpoint può restituire tipi di risposta diversi in scenari diversi, è possibile fornire metadati nei modi seguenti:

  • Chiamare il Produces metodo di estensione più volte, come illustrato nell'esempio seguente:

    app.MapGet("/api/todoitems/{id}", async (int id, TodoDb db) =>
         await db.Todos.FindAsync(id) 
         is Todo todo
         ? Results.Ok(todo) 
         : Results.NotFound())
   .Produces<Todo>(StatusCodes.Status200OK)
   .Produces(StatusCodes.Status404NotFound);

  • Usare Results<TResult1,TResult2,TResultN> nella firma e TypedResults nel corpo del gestore, come illustrato nell'esempio seguente:

    app.MapGet("/book/{id}", Results<Ok<Book>, NotFound> (int id, List<Book> bookList) =>
{
    return bookList.FirstOrDefault((i) => i.Id == id) is Book book
     ? TypedResults.Ok(book)
     : TypedResults.NotFound();
});

    I Results<TResult1,TResult2,TResultN>tipi di unione dichiarano che un gestore di route restituisce più IResulttipi concreti che implementano e uno qualsiasi di questi tipi che implementa IEndpointMetadataProvider contribuirà ai metadati dell'endpoint.

    I tipi di unione implementano operatori cast impliciti. Questi operatori consentono al compilatore di convertire automaticamente i tipi specificati negli argomenti generici in un'istanza del tipo di unione. Questa funzionalità offre il vantaggio aggiunto di fornire un controllo in fase di compilazione che un gestore di route restituisce solo i risultati che dichiara. Se si tenta di restituire un tipo non dichiarato come uno degli argomenti generici, si Results<TResult1,TResult2,TResultN> verifica un errore di compilazione.

Descrivere il corpo e i parametri della richiesta

Oltre a descrivere i tipi restituiti da un endpoint, OpenAPI supporta anche l'annotazione degli input utilizzati da un'API. Questi input rientrano in due categorie:

  • Parametri visualizzati nel percorso, nella stringa di query, nelle intestazioni o nei cookie
  • Dati trasmessi come parte del corpo della richiesta

Il framework deduce automaticamente i tipi per i parametri della richiesta nel percorso, nella query e nella stringa di intestazione in base alla firma del gestore di route.

Per definire il tipo di input trasmesso come corpo della richiesta, configurare le proprietà usando il Accepts metodo di estensione per definire il tipo di oggetto e il tipo di contenuto previsti dal gestore della richiesta. Nell'esempio seguente l'endpoint accetta un Todo oggetto nel corpo della richiesta con un tipo di contenuto previsto di application/xml.

app.MapPost("/todos/{id}", (int id, Todo todo) => ...)
  .Accepts<Todo>("application/xml");

Oltre al Accepts metodo di estensione, un tipo di parametro può descrivere la propria annotazione implementando l'interfaccia IEndpointParameterMetadataProvider . Ad esempio, il tipo seguente Todo aggiunge un'annotazione che richiede un corpo della richiesta con un application/xml tipo di contenuto.

public class Todo : IEndpointParameterMetadataProvider
{
    public static void PopulateMetadata(ParameterInfo parameter, EndpointBuilder builder)
    {
        builder.Metadata.Add(new ConsumesAttribute(typeof(Todo), isOptional: false, "application/xml"));
    }
}

Quando non viene fornita alcuna annotazione esplicita, il framework tenta di determinare il tipo di richiesta predefinito se è presente un parametro del corpo della richiesta nel gestore dell'endpoint. L'inferenza usa le euristiche seguenti per produrre l'annotazione:

  • I parametri del corpo della richiesta letti da un modulo tramite l'attributo [FromForm] vengono descritti con il multipart/form-data tipo di contenuto.
  • Tutti gli altri parametri del corpo della richiesta sono descritti con il application/json tipo di contenuto.
  • Il corpo della richiesta viene considerato facoltativo se è nullable o se la AllowEmpty proprietà è impostata sull'attributo FromBody .

Supporto del controllo delle versioni delle API

Le API minime supportano il controllo delle versioni delle API tramite il pacchetto Asp.Versioning.Http. Esempi di configurazione del controllo delle versioni con API minime sono disponibili nel repository di controllo delle versioni dell'API.

ASP.NET codice sorgente OpenAPI core in GitHub

Risorse aggiuntive

Un'app per le API minima può descrivere la specifica OpenAPI per i gestori di route usando Swashbuckle.

Per informazioni sul supporto per OpenAPI nelle API basate su controller, vedere la versione .NET 9 di questo articolo.

Il codice seguente è un'app ASP.NET Core tipica con supporto OpenAPI:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new() { Title = builder.Environment.ApplicationName,
                               Version = "v1" });
});

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.UseSwagger(); // UseSwaggerUI Protected by if (env.IsDevelopment())
    app.UseSwaggerUI(c => c.SwaggerEndpoint("/swagger/v1/swagger.json",
                                    $"{builder.Environment.ApplicationName} v1"));
}

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

app.Run();

Escludere la descrizione OpenAPI

Nell'esempio seguente l'endpoint /skipme viene escluso dalla generazione di una descrizione OpenAPI:

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI(); // UseSwaggerUI Protected by if (env.IsDevelopment())
}

app.MapGet("/swag", () => "Hello Swagger!");
app.MapGet("/skipme", () => "Skipping Swagger.")
                    .ExcludeFromDescription();

app.Run();

Descrivere i tipi di risposta

Nell'esempio seguente vengono usati i tipi di risultati predefiniti per personalizzare la risposta:

app.MapGet("/api/todoitems/{id}", async (int id, TodoDb db) =>
         await db.Todos.FindAsync(id) 
         is Todo todo
         ? Results.Ok(todo) 
         : Results.NotFound())
   .Produces<Todo>(StatusCodes.Status200OK)
   .Produces(StatusCodes.Status404NotFound);

Aggiungere id operazione a OpenAPI

app.MapGet("/todoitems2", async (TodoDb db) =>
    await db.Todos.ToListAsync())
    .WithName("GetToDoItems");

Aggiungere tag alla descrizione OpenAPI

Il codice seguente usa un tag di raggruppamento OpenAPI:

app.MapGet("/todoitems", async (TodoDb db) =>
    await db.Todos.ToListAsync())
    .WithTags("TodoGroup");