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'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 JSschema ON fornito da System.Text.Json.
• È compatibile con AoT nativo.

Installazione del pacchetto

Installare il pacchetto Microsoft.AspNetCore.OpenApi:

Install-Package Microsoft.AspNetCore.OpenApi -IncludePrerelease

dotnet add package Microsoft.AspNetCore.OpenApi --prerelease

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

Install-Package Microsoft.Extensions.ApiDescription.Server -IncludePrerelease

dotnet add package Microsoft.Extensions.ApiDescription.Server --prerelease

Configurare la generazione di documenti OpenAPI

Il codice seguente:

• Aggiunge servizi OpenAPI.
• Abilita l'endpoint per la visualizzazione del documento OpenAPI in JSformato ON.

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.

Inclusione dei metadati OpenAPI in un'app Web ASP.NET

ASP.NET raccoglie i metadati dagli endpoint dell'app Web e lo usa per generare un documento OpenAPI. Nelle app basate su controller i metadati vengono raccolti da attributi come [EndpointDescription], [HttpPost]e [Produces]. Nelle API minime, i metadati possono essere raccolti dagli attributi, ma possono anche essere impostati usando metodi di estensione e altre strategie, ad esempio la restituzione TypedResults dai gestori di route. Nella tabella seguente viene fornita una panoramica dei metadati raccolti e delle strategie per impostarlo.

ASP.NET Core non raccoglie metadati dai commenti del documento XML.

Le sezioni seguenti illustrano come includere metadati in un'app per personalizzare il documento OpenAPI generato.

Riepilogo e descrizione

Il riepilogo e la descrizione dell'endpoint possono essere impostati usando gli [EndpointSummary] attributi e [EndpointDescription] o nelle API minime, usando i WithSummary metodi di estensione e WithDescription .

• [EndpointSummary]: EndpointSummaryAttribute
• [EndpointDescription]: EndpointDescriptionAttribute
• WithSummary: WithSummary
• WithDescription: WithDescription

app.MapGet("/extension-methods", () => "Hello world!")
  .WithSummary("This is a summary.")
  .WithDescription("This is a description.");

app.MapGet("/attributes",
  [EndpointSummary("This is a summary.")]
  [EndpointDescription("This is a description.")]
  () => "Hello world!");

  [EndpointSummary("This is a summary.")]
  [EndpointDescription("This is a description.")]
  [HttpGet("attributes")]
  public IResult Attributes()
  {
      return Results.Ok("Hello world!");
  }

tag

OpenAPI supporta la specifica di tag in ogni endpoint sotto forma di categorizzazione. Nelle app basate su controller, il nome del controller viene aggiunto automaticamente come tag in ognuno dei relativi endpoint, ma può essere sottoposto a override usando l'attributo [Tags] . Nelle API minime, i tag possono essere impostati usando l'attributo [Tags] o il metodo di WithTags estensione.

• [Tags]: TagsAttribute
• WithTags: WithTags

app.MapGet("/extension-methods", () => "Hello world!")
  .WithTags("todos", "projects");

app.MapGet("/attributes",
  [Tags("todos", "projects")]
  () => "Hello world!");

  [Tags(["todos", "projects"])]
  [HttpGet("attributes")]
  public IResult Attributes()
  {
      return Results.Ok("Hello world!");
  }

operationId

OpenAPI supporta un operationId in ogni endpoint come identificatore univoco o nome per l'operazione. Nelle app basate su controller è possibile impostare operationId usando l'attributo [EndpointName] . Nelle API minime, è possibile impostare operationId usando l'attributo [EndpointName] o il metodo di WithName estensione.

• [EndpointName]: EndpointNameAttribute
• WithName: WithName

app.MapGet("/extension-methods", () => "Hello world!")
  .WithName("FromExtensionMethods");

app.MapGet("/attributes",
  [EndpointName("FromAttributes")]
  () => "Hello world!");

  [EndpointName("FromAttributes")]
  [HttpGet("attributes")]
  public IResult Attributes()
  {
      return Results.Ok("Hello world!");
  }

parameters

OpenAPI supporta l'annotazione del percorso, della stringa di query, dell'intestazione e cookie dei parametri utilizzati da un'API.

Il framework deduce automaticamente i tipi per i parametri di richiesta in base alla firma del gestore di route.

L'attributo [Description] può essere usato per fornire una descrizione per un parametro.

• Description

app.MapGet("/attributes",
  ([Description("This is a description.")] string name) => "Hello world!");

  [HttpGet("attributes")]
  public IResult Attributes([Description("This is a description.")] string name)
  {
      return Results.Ok("Hello world!");
  }

requestBody

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 AcceptsMetadata(["application/xml", "text/xml"], typeof(XmlBody)));
    }
}

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 .

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 Produces metodo di estensione nell'endpoint.
• Tramite l'attributo ProducesResponseType nel gestore di route.
• RestituendoTypedResults 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 o o ProducesValidationProblem può TypedResults.Problem essere usato per aggiungere l'annotazione appropriata ai metadati dell'endpoint.

Quando non sono presenti annotazioni esplicite fornite da una di queste strategie, 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.

Esclusione di endpoint dal documento generato

Per impostazione predefinita, tutti gli endpoint definiti in un'app sono documentati nel file OpenAPI generato. Le API minime supportano due strategie per escludere un determinato endpoint dal documento OpenAPI, usando:

• ExcludeFromDescription
• ExcludeFromDescriptionAttribute

L'esempio seguente illustra le diverse strategie per escludere un determinato endpoint dal documento OpenAPI generato.

app.MapGet("/extension-method", () => "Hello world!")
  .ExcludeFromDescription();

app.MapGet("/attributes",
  [ExcludeFromDescription]
  () => "Hello world!");

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, è possibile limitare l'accesso al documento OpenAPI. Ad esempio, 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();

Trasformatori di documento OpenAPI

Questa sezione illustra come personalizzare i documenti OpenAPI con trasformatori.

Personalizzare documenti OpenAPI con trasformatori

I trasformatori forniscono un'API per la modifica del documento OpenAPI con personalizzazioni definite dall'utente. I trasformatori sono utili per scenari come:

• Aggiunta di parametri a tutte le operazioni in un documento.
• Modifica delle descrizioni per parametri o operazioni.
• Aggiunta di informazioni di primo livello al documento OpenAPI.

I trasformatori rientrano in due categorie:

• I trasformatori di documento hanno accesso all'intero documento OpenAPI. Questi possono essere usati per apportare modifiche globali al documento.
• I trasformatori di operazione si applicano a ogni singola operazione. Ogni singola operazione è una combinazione di percorso e metodo HTTP. Possono essere usati per modificare parametri o risposte sugli endpoint.

I trasformatori possono essere registrati nel documento chiamando il AddDocumentTransformer metodo sull'oggetto OpenApiOptions . Il frammento di codice seguente illustra diversi modi per registrare i trasformatori nel documento:

• Registrare un trasformatore di documento usando un delegato.
• Registrare un trasformatore di documento usando un'istanza di IOpenApiDocumentTransformer.
• Registrare un trasformatore di documento usando un'attivazione IOpenApiDocumentTransformerdell'inserimento delle dipendenze.
• Registrare un trasformatore di operazione usando un delegato.
• Registrare un trasformatore di operazione usando un'istanza di IOpenApiOperationTransformer.
• Registrare un trasformatore di operazione utilizzando un'eccezione attivata dall'inserimento IOpenApiOperationTransformerdelle dipendenze.
• Registrare un trasformatore di schema usando un delegato.
• Registrare un trasformatore di schema usando un'istanza di IOpenApiSchemaTransformer.
• Registrare un trasformatore di schema usando un'attivazione IOpenApiSchemaTransformerdell'inserimento delle dipendenze.

using Microsoft.AspNetCore.OpenApi;
using Microsoft.OpenApi.Models;

var builder = WebApplication.CreateBuilder();

builder.Services.AddOpenApi(options =>
{
    options.AddDocumentTransformer((document, context, cancellationToken) 
                             => Task.CompletedTask);
    options.AddDocumentTransformer(new MyDocumentTransformer());
    options.AddDocumentTransformer<MyDocumentTransformer>();
    options.AddOperationTransformer((operation, context, cancellationToken)
                            => Task.CompletedTask);
    options.AddOperationTransformer(new MyOperationTransformer());
    options.AddOperationTransformer<MyOperationTransformer>();
    options.AddSchemaTransformer((schema, context, cancellationToken)
                            => Task.CompletedTask);
    options.AddSchemaTransformer(new MySchemaTransformer());
    options.AddSchemaTransformer<MySchemaTransformer>();
});

var app = builder.Build();

app.MapOpenApi();

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

app.Run();

Ordine di esecuzione per trasformatori

I trasformatori sono eseguiti nell'ordine first-in first-out in base alla registrazione. Nel frammento di codice seguente, il trasformatore di documento ha accesso alle modifiche apportate dal trasformatore di operazione:

var builder = WebApplication.CreateBuilder();

builder.Services.AddOpenApi(options =>
{
    options.AddOperationTransformer((operation, context, cancellationToken)
                                     => Task.CompletedTask);
    options.AddDocumentTransformer((document, context, cancellationToken)
                                     => Task.CompletedTask);
});

var app = builder.Build();

app.MapOpenApi();

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

app.Run();

Usare trasformatori di documento

I trasformatori di documento hanno accesso a un oggetto contesto che include:

• Nome del documento da modificare.
• Elenco di ApiDescriptionGroups associato al documento.
• Oggetto IServiceProvider utilizzato nella generazione di documenti.

I trasformatori di documento possono anche modificare il documento OpenAPI generato. L'esempio seguente illustra un trasformatore di documento che aggiunge alcune informazioni sull'API al documento OpenAPI.

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

var builder = WebApplication.CreateBuilder();

builder.Services.AddOpenApi(options =>
{
    options.AddDocumentTransformer((document, context, cancellationToken) =>
    {
        document.Info = new()
        {
            Title = "Checkout API",
            Version = "v1",
            Description = "API for processing checkouts from cart."
        };
        return Task.CompletedTask;
    });
});

var app = builder.Build();

app.MapOpenApi();

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

app.Run();

I trasformatori di documento attivati dal servizio possono usare istanze di inserimento delle dipendenze per modificare l'app. L'esempio seguente illustra un trasformatore di documento che usa il IAuthenticationSchemeProvider servizio dal livello di autenticazione. Controlla se gli schemi correlati al bearer JWT sono registrati nell'app e li aggiunge al livello principale del documento OpenAPI:

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.AddOpenApi(options =>
{
    options.AddDocumentTransformer<BearerSecuritySchemeTransformer>();
});

var app = builder.Build();

app.MapOpenApi();

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

app.Run();

internal sealed class BearerSecuritySchemeTransformer(IAuthenticationSchemeProvider authenticationSchemeProvider) : IOpenApiDocumentTransformer
{
    public async Task TransformAsync(OpenApiDocument document, OpenApiDocumentTransformerContext context, CancellationToken cancellationToken)
    {
        var authenticationSchemes = await authenticationSchemeProvider.GetAllSchemesAsync();
        if (authenticationSchemes.Any(authScheme => authScheme.Name == "Bearer"))
        {
            var requirements = new Dictionary<string, OpenApiSecurityScheme>
            {
                ["Bearer"] = new OpenApiSecurityScheme
                {
                    Type = SecuritySchemeType.Http,
                    Scheme = "bearer", // "bearer" refers to the header name here
                    In = ParameterLocation.Header,
                    BearerFormat = "Json Web Token"
                }
            };
            document.Components ??= new OpenApiComponents();
            document.Components.SecuritySchemes = requirements;
        }
    }
}

I trasformatori di documento sono univoci per l'istanza del documento a cui sono associati. Nell'esempio seguente un trasformatore:

• Registra i requisiti correlati all'autenticazione nel internal documento.
• Lascia invariato il public documento.

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.AddOpenApi("internal", options =>
{
    options.AddDocumentTransformer<BearerSecuritySchemeTransformer>();
});
builder.Services.AddOpenApi("public");

var app = builder.Build();

app.MapOpenApi();

app.MapGet("/world", () => "Hello world!")
    .WithGroupName("internal");
app.MapGet("/", () => "Hello universe!")
    .WithGroupName("public");

app.Run();

internal sealed class BearerSecuritySchemeTransformer(IAuthenticationSchemeProvider authenticationSchemeProvider) : IOpenApiDocumentTransformer
{
    public async Task TransformAsync(OpenApiDocument document, OpenApiDocumentTransformerContext context, CancellationToken cancellationToken)
    {
        var authenticationSchemes = await authenticationSchemeProvider.GetAllSchemesAsync();
        if (authenticationSchemes.Any(authScheme => authScheme.Name == "Bearer"))
        {
            // Add the security scheme at the document level
            var requirements = new Dictionary<string, OpenApiSecurityScheme>
            {
                ["Bearer"] = new OpenApiSecurityScheme
                {
                    Type = SecuritySchemeType.Http,
                    Scheme = "bearer", // "bearer" refers to the header name here
                    In = ParameterLocation.Header,
                    BearerFormat = "Json Web Token"
                }
            };
            document.Components ??= new OpenApiComponents();
            document.Components.SecuritySchemes = requirements;

            // Apply it as a requirement for all operations
            foreach (var operation in document.Paths.Values.SelectMany(path => path.Operations))
            {
                operation.Value.Security.Add(new OpenApiSecurityRequirement
                {
                    [new OpenApiSecurityScheme { Reference = new OpenApiReference { Id = "Bearer", Type = ReferenceType.SecurityScheme } }] = Array.Empty<string>()
                });
            }
        }
    }
}

Usare trasformatori di operazione

Le operazioni sono combinazioni univoche di percorsi e metodi HTTP in un documento OpenAPI. I trasformatori di operazione sono utili quando si modifica:

• Deve essere eseguito a ogni endpoint in un'app o
• Applicato in modo condizionale a determinate route.

I trasformatori di operazione hanno accesso a un oggetto contesto che contiene:

• Nome del documento a cui appartiene l'operazione.
• Classe ApiDescription associata all'operazione.
• Oggetto IServiceProvider utilizzato nella generazione di documenti.

Ad esempio, il trasformatore di operazione seguente aggiunge 500 come codice di stato della risposta supportato da tutte le operazioni nel documento.

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.AddOpenApi(options =>
{
    options.AddOperationTransformer((operation, context, cancellationToken) =>
    {
        operation.Responses.Add("500", new OpenApiResponse { Description = "Internal server error" });
        return Task.CompletedTask;
    });
});

var app = builder.Build();

app.MapOpenApi();

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

app.Run();

Risorse aggiuntive

• Usare i documenti OpenAPI generati
• Specifica 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 cookienei
• 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

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");