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 le vulnerabilità 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>

API v. Operazione API v. Punto finale API

Le sezioni seguenti illustrano le differenze tra un'API, un endpoint API e un'operazione API nel contesto della documentazione di ASP.NET Core e OpenAPI.

API (Application Programming Interface)

Un'API è un set di regole e protocolli per la compilazione e l'interazione con le applicazioni software. Definisce il modo in cui i diversi componenti software devono comunicare. In generale lo sviluppo Web, "API" si riferisce in genere a un servizio Web che espone funzionalità su HTTP.

In ASP.NET Core, un'API viene in genere compilata usando controller o API minime, che gestiscono le richieste HTTP in ingresso e restituiscono risposte.

Le convenzioni di denominazione interne di ASP.NET Core a volte utilizzano "API" in modo diverso. Ad esempio, in Esplora API un "ApiDescription" rappresenta effettivamente un'operazione API anziché il servizio API completo. Questa distinzione riflette le convenzioni di denominazione interne e talvolta differisce dalla definizione più ampia usata qui.

Per altre informazioni su Esplora API, vedere Introduzione ad ApiExplorer in ASP.NET Core .

Operazione API

Un'operazione API rappresenta un'azione o una funzionalità specifica fornita da un'API. In ASP.NET Core corrisponde a:

• Metodi di azione del controller nelle API di tipo MVC
• Gestori di route nelle API minime

Ogni operazione viene definita dal relativo metodo HTTP (GET, POST, PUTe così via), dal percorso, dai parametri e dalle risposte.

Punto di accesso API

Un endpoint API è un URL specifico:

• Che rappresenta una risorsa o una funzionalità specifica esposta dall'API.
• Fornisce l'indirizzo esatto a cui un client deve inviare una richiesta HTTP per interagire con un'operazione API specifica.

Un endpoint è una combinazione dell'URL di base dell'API e di un percorso specifico della risorsa desiderata, insieme ai metodi HTTP supportati:

• Per le API basate su controller, gli endpoint uniscono il modello di route con il controller e l'azione.
• Per le API minime, gli endpoint vengono definiti in modo esplicito con app.MapGet(), app.MapPost()e così via.

Ad esempio, l'endpoint api/products/{id} che supporta le operazioni seguenti:

• GET /api/products/{id}
• PUT /api/products/{id}
• PATCH /api/products/{id}
• Delete /api/products/{id}
• HEAD /api/products/{id}

Gli endpoint includono spesso parametri di query, ad esempio GET /api/products?category=electronics&sort=price

Documentazione di OpenAPI

Nel contesto di OpenAPI, la documentazione descrive l'API nel suo complesso, inclusi tutti gli endpoint e le operazioni. OpenAPI offre un modo strutturato per documentare le API, rendendo più semplice per gli sviluppatori comprendere come interagire con essi.

Le operazioni API sono l'obiettivo principale della documentazione di OpenAPI. La specifica OpenAPI organizza la documentazione in base alle operazioni, raggruppate in base ai percorsi (endpoint). Ogni operazione viene descritta con dettagli come parametri, corpi delle richieste, risposte e altro ancora. Questo formato strutturato consente agli strumenti di generare automaticamente librerie client, stub server e documentazione interattiva.

In un documento OpenAPI:

• L'intero documento descrive l'API nel suo complesso
• Ogni elemento di percorso (ad esempio /api/products/{id}) rappresenta un endpoint
• In ogni percorso i metodi HTTP (GET, POST, PUTe così via) definiscono le operazioni
• Ogni operazione contiene informazioni dettagliate sui parametri, il corpo della richiesta, le risposte e così via.

Esempio in formato JSON OpenAPI:

json{
  "paths": {
    "/api/products/{id}": {  // This is the endpoint
      "get": {  // This is the operation
        "summary": "Get a product by ID",
        "parameters": [...],
        "responses": {...}
      },
      "put": {  // Another operation on the same endpoint
        "summary": "Update a product",
        "parameters": [...],
        "responses": {...}
      }
    }
  }
}

Confronto tra API, operazioni API ed endpoint API

La tabella seguente riepiloga le differenze tra un'API, un'operazione API e un endpoint API:

Concetto	Operazione API	Punto di accesso API
Definizione	Descrizione logica di un'azione API: metodo + percorso + comportamento	La route HTTP effettivamente configurata che è in ascolto delle richieste
livello	Concettualmente, quale azione può accadere	Precisamente, quale URL e metodo vengono confrontati
Associato a	Progettazione/specifica dell'API OpenAPI	Routing di ASP.NET Core in fase di esecuzione
Descrive	Che cosa fa l'API, ad esempio, "crea prodotto"	Dove e come chiamarlo, ad esempio , POST https://localhost:7099/api/productsPOST https://contoso.com/api/products
In ASP.NET Core	Azioni del controller o metodi API minimi, prima che il routing venga risolto	Oggetti degli endpoint risolti durante il runtime

ASP.NET codice sorgente OpenAPI core in GitHub

• AddOpenApi
• OpenApiDocumentService
• OpenApiOptions

Risorse aggiuntive

• Autenticazione e autorizzazione in API minime