Supporto openAPI nelle app per le API principali di ASP.NET

ASP.NET Core supporta la generazione di documenti OpenAPI in app basate su controller e API minime. La specifica OpenAPI è uno standard indipendente dal linguaggio di programmazione per la documentazione delle API HTTP. Questo standard è supportato nelle app ASP.NET Core tramite una combinazione di API predefinite e librerie open source. L'integrazione OpenAPI in un'applicazione presenta tre aspetti chiave:

• Generazione di informazioni sugli endpoint nell'app.
• Raccolta delle informazioni in un formato corrispondente allo schema OpenAPI.
• Esposizione del documento OpenAPI generato tramite un'interfaccia utente visiva o un file serializzato.

ASP.NET le app core forniscono supporto predefinito per la generazione di informazioni sugli endpoint in un'app tramite il Microsoft.AspNetCore.OpenApi pacchetto.

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.AddOpenApi();

var app = builder.Build();

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

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

app.Run();

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

Nel codice evidenziato precedente:

• AddOpenApi registra i servizi necessari per la generazione di documenti OpenAPI nel contenitore di inserimento delle dipendenze dell'applicazione.
• MapOpenApi aggiunge un endpoint all'applicazione per visualizzare il documento OpenAPI serializzato in JSON. L'endpoint OpenAPI è limitato all'ambiente di sviluppo per ridurre al minimo il rischio di esporre informazioni riservate e ridurre la superficie di attacco nell'ambiente di produzione.

pacchetto NuGet Microsoft.AspNetCore.OpenApi

Il Microsoft.AspNetCore.OpenApi 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.

Per usare il Microsoft.AspNetCore.OpenApi pacchetto, aggiungerlo come PackageReference a un file di progetto:

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

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

  <PropertyGroup>
    <OpenApiGenerateDocuments>true</OpenApiGenerateDocuments>
    <OpenApiDocumentsDirectory>$(MSBuildProjectDirectory)</OpenApiDocumentsDirectory>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="9.0.*-*" />
    <PackageReference Include="Microsoft.Extensions.ApiDescription.Server" Version="9.0.*-*">
      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
      <PrivateAssets>all</PrivateAssets>
    </PackageReference>
  </ItemGroup>

</Project>

Per altre informazioni sul Microsoft.AspNetCore.OpenApi pacchetto, vedere Generare documenti OpenAPI.

pacchetto NuGet Microsoft.Extensions.ApiDescription.Server

Il Microsoft.Extensions.ApiDescription.Server pacchetto fornisce il supporto per la generazione di documenti OpenAPI in fase di compilazione e la serializzazione.

Per usare Microsoft.Extensions.ApiDescription.Server, aggiungerlo come PackageReference a un file di progetto. La generazione di documenti in fase di compilazione è abilitata impostando la OpenApiGenerateDocuments proprietà . Per impostazione predefinita, il documento OpenAPI generato viene salvato nella obj directory, ma è possibile personalizzare la directory di output impostando la OpenApiDocumentsDirectory proprietà .

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

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

  <PropertyGroup>
    <OpenApiGenerateDocuments>true</OpenApiGenerateDocuments>
    <OpenApiDocumentsDirectory>$(MSBuildProjectDirectory)</OpenApiDocumentsDirectory>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="9.0.*-*" />
    <PackageReference Include="Microsoft.Extensions.ApiDescription.Server" Version="9.0.*-*">
      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
      <PrivateAssets>all</PrivateAssets>
    </PackageReference>
  </ItemGroup>

</Project>

ASP.NET codice sorgente OpenAPI core in GitHub

• AddOpenApi
• OpenApiDocumentService
• OpenApiOptions

Risorse aggiuntive

• Autenticazione e autorizzazione in API minime

La specifica OpenAPI è uno standard indipendente dal linguaggio di programmazione per la documentazione delle API HTTP. Questo standard è supportato in API minime tramite una combinazione di API predefinite e librerie open source. L'integrazione OpenAPI in un'applicazione presenta tre aspetti chiave:

• Generazione di informazioni sugli endpoint nell'app.
• Raccolta delle informazioni in un formato corrispondente allo schema OpenAPI.
• Esposizione dello schema OpenAPI generato tramite un'interfaccia utente visiva o un file serializzato.

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.