Generare documenti OpenAPI

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.
• WithNameIEndpointNameMetadata: 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:

• Tramite il metodo di Produces estensione nell'endpoint
• Tramite l'attributo ProducesResponseType nel gestore di route
• Restituendo TypedResults dal gestore di route

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

• WithOpenApi
• OpenApiGenerator

Risorse aggiuntive

• Autenticazione e autorizzazione in API minime