C# Academy · Lezione

Generazione di documenti OpenAPI

Produca specifiche API leggibili dalle macchine.

Generazione di documenti OpenAPI è una lezione C# Academy gratuita su CoddyKit. Questa è la lezione 3 di 4. Puoi leggere la lezione completa qui gratuitamente — poi esercitati direttamente nel browser con un editor di codice integrato e un tutor IA disponibile 24/7. Fa parte del percorso di apprendimento C# Academy, e i tuoi progressi si sincronizzano tra il web e l'app CoddyKit. Il corso C# Academy include 4 lezioni in totale.

Che cos'è OpenAPI

OpenAPI è una descrizione standard e leggibile dalle macchine di un'API HTTP. Da questa descrizione è possibile generare documentazione, SDK client e strumenti di test.

.NET 9 include la generazione integrata dei documenti OpenAPI e sostituisce la precedente dipendenza da Swashbuckle per molte applicazioni.

// OpenAPI document = JSON describing paths, schemas, params

Il pacchetto Microsoft.AspNetCore.OpenApi

Il supporto integrato risiede in Microsoft.AspNetCore.OpenApi. Nei template di .NET 9 è già referenziato.

dotnet add package Microsoft.AspNetCore.OpenApi

AddOpenApi

Registri il generatore di documenti con AddOpenApi nella configurazione dei servizi.

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddOpenApi();

MapOpenApi

MapOpenApi espone il documento generato tramite un endpoint. Per impostazione predefinita, lo rende disponibile all'indirizzo /openapi/v1.json.

var app = builder.Build();

app.MapOpenApi();   // GET /openapi/v1.json

app.Run();

Limitazione all'ambiente di sviluppo

È comune esporre il documento solo durante lo sviluppo, per evitare di rivelare la superficie dell'API in produzione.

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

Descrizione degli endpoint

I metadati OpenAPI vengono arricchiti a partire dal codice. Usi WithSummary, WithDescription e WithTags sugli endpoint delle Minimal API.

app.MapGet("/products/{id}", (int id) => Results.Ok())
   .WithSummary("Get a product by id")
   .WithDescription("Returns a single product or 404.")
   .WithTags("Products");

Documentazione delle risposte

Dichiari i tipi di risposta e i codici di stato, in modo che il documento li elenchi accuratamente.

app.MapGet("/products/{id}", (int id) => Results.Ok())
   .Produces<Product>(StatusCodes.Status200OK)
   .Produces(StatusCodes.Status404NotFound);

Trasformatori del documento

Personalizzi l'intero documento, inclusi titolo, versione e server, con un trasformatore del documento passato a AddOpenApi.

builder.Services.AddOpenApi(options =>
{
    options.AddDocumentTransformer((doc, ctx, ct) =>
    {
        doc.Info.Title = "Catalog API";
        doc.Info.Version = "1.0";
        return Task.CompletedTask;
    });
});

Trasformatori delle operazioni

Un trasformatore delle operazioni modifica le singole operazioni, ad esempio aggiungendo un parametro header comune a ogni endpoint.

options.AddOperationTransformer((operation, ctx, ct) =>
{
    operation.Responses.TryAdd("500",
        new OpenApiResponse { Description = "Server error" });
    return Task.CompletedTask;
});

Aggiunta di un'interfaccia utente

Il generatore integrato produce il documento JSON, ma non un'interfaccia utente. Lo abbini a un visualizzatore come Scalar o Swagger UI.

// dotnet add package Scalar.AspNetCore
app.MapOpenApi();
app.MapScalarApiReference();  // interactive docs at /scalar/v1

Generazione durante la compilazione

È possibile generare il file OpenAPI durante la compilazione, senza un server in esecuzione, usando gli strumenti Microsoft.Extensions.ApiDescription.Server, utili per la generazione dei client in CI.

// .csproj
// <OpenApiGenerateDocuments>true</OpenApiGenerateDocuments>
// produces obj/<App>.json on build

Verifica rapida

Verifichi le nozioni di base su OpenAPI in .NET 9.

Riepilogo

Ha generato documenti OpenAPI:

AddOpenApi() registra il generatore; MapOpenApi() espone il JSON.
Arricchisca gli endpoint con WithSummary, Produces e i tag.
I trasformatori del documento e delle operazioni personalizzano l'output.
Abbini Scalar o Swagger UI per una visualizzazione interattiva.

Prossimo argomento: documentazione delle API versionate.

Domande Frequenti

La lezione «Generazione di documenti OpenAPI» è gratuita?

Sì — il testo completo di «Generazione di documenti OpenAPI» è gratuito qui sul web. Per esercitarvi in modo interattivo (un editor di codice integrato e un tutor IA 24/7) e sbloccare il resto del corso C# Academy, passa a CoddyKit PRO. Il corso C# Academy include 4 lezioni in totale.

Cosa imparerò in «Generazione di documenti OpenAPI»?

Produca specifiche API leggibili dalle macchine. Eserciti C# Academy con codice pratico che esegui direttamente nel browser, e un tutor IA 24/7 risponde alle tue domande mentre lavori sulla lezione.

Ho bisogno di esperienza per iniziare C# Academy?

Non è richiesta alcuna esperienza precedente. C# Academy su CoddyKit è strutturato per principianti e studenti avanzati, quindi puoi iniziare da qui o dall'inizio e procedere al tuo ritmo. Questa è la lezione 3 di 4.

Quanto tempo richiede la lezione «Generazione di documenti OpenAPI»?

La maggior parte delle lezioni CoddyKit richiede circa 5–10 minuti. Ogni lezione è breve e interattiva, quindi fai progressi costanti e riprendi esattamente da dove hai lasciato su web e app.

Posso scrivere ed eseguire codice in questa lezione C# Academy?

Sì. Ogni lezione C# Academy include un editor di codice integrato, quindi scrivi ed esegui codice reale direttamente nel tuo browser e ricevi feedback istantaneo dall'IA — nessuna configurazione locale necessaria.

Tutte le lezioni di questo corso

← Torna a C# Academy