C# Academy · Lezione

OpenAPI, versionamento e distribuzione

Generi la documentazione Swagger/OpenAPI, versioni le API e distribuisca una Minimal API in Azure App Service o in container.

OpenAPI, versionamento e distribuzione è una lezione C# Academy gratuita su CoddyKit. Questa è la lezione 4 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.

OpenAPI nelle Minimal API

OpenAPI (in precedenza Swagger) genera documentazione interattiva per le API. In .NET 9, AddOpenApi() è integrato. Per le versioni precedenti, utilizzi Swashbuckle.AspNetCore.

Aggiungere Swagger con Swashbuckle

Installi Swashbuckle, lo configuri nei servizi e aggiunga il middleware per pubblicare la specifica e Swagger UI.

// dotnet add package Swashbuckle.AspNetCore

builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen(opt =>
    opt.SwaggerDoc("v1", new() { Title = "Products API", Version = "v1" }));

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

Annotare gli endpoint per OpenAPI

Utilizzi Produces, ProducesProblem, WithSummary e WithDescription per arricchire la specifica OpenAPI generata.

app.MapGet("/products/{id}", GetProduct)
   .WithName("GetProductById")
   .WithSummary("Get a product by ID")
   .WithDescription("Returns the product matching the given numeric ID.")
   .Produces<ProductDto>(200)
   .Produces<ProblemDetails>(404)
   .WithTags("Products");

Versioning delle API con i gruppi di route

Una semplice strategia di versioning utilizza gruppi di route con un prefisso che indica la versione. Per il versioning di base non è necessario alcun pacchetto aggiuntivo.

var v1 = app.MapGroup("/api/v1").WithTags("v1");
var v2 = app.MapGroup("/api/v2").WithTags("v2");

v1.MapGet("/products", GetProductsV1);
v2.MapGet("/products", GetProductsV2); // different DTO shape

// Clients use /api/v1/products or /api/v2/products

Asp.Versioning per il versioning tramite header o query string

Il pacchetto Asp.Versioning.Http aggiunge alle Minimal API il versioning tramite query string, header e segmento dell'URL, con piena integrazione con OpenAPI.

// dotnet add package Asp.Versioning.Http

builder.Services.AddApiVersioning(opt =>
{
    opt.DefaultApiVersion = new ApiVersion(1, 0);
    opt.AssumeDefaultVersionWhenUnspecified = true;
    opt.ApiVersionReader = new QueryStringApiVersionReader("api-version");
});

// /products?api-version=2.0
app.MapGet("/products", GetProducts)
   .HasApiVersion(2, 0);

Generare una specifica separata per ogni versione

Configuri Swashbuckle per generare documenti OpenAPI separati per ogni versione, in modo che i consumatori vedano solo gli endpoint pertinenti alla loro versione.

builder.Services.AddSwaggerGen(opt =>
{
    opt.SwaggerDoc("v1", new() { Title = "API", Version = "v1" });
    opt.SwaggerDoc("v2", new() { Title = "API", Version = "v2" });
});

app.UseSwaggerUI(opt =>
{
    opt.SwaggerEndpoint("/swagger/v1/swagger.json", "v1");
    opt.SwaggerEndpoint("/swagger/v2/swagger.json", "v2");
});

Pubblicare un binario autonomo

Pubblicare la Minimal API come singolo binario autonomo, senza bisogno del runtime .NET nel computer di destinazione.

# Publish for Linux x64 as self-contained
dotnet publish -c Release -r linux-x64 --self-contained true

# Run the output binary
./bin/Release/net9.0/linux-x64/publish/MyApi

# Optionally single-file:
# dotnet publish -c Release -r linux-x64 -p:PublishSingleFile=true

Creare un container con Docker

Inserisca l'API in un'immagine Docker utilizzando le immagini base ufficiali di .NET. Un Dockerfile multi-stage mantiene ridotte le dimensioni dell'immagine finale.

# Dockerfile (multi-stage)
FROM mcr.microsoft.com/dotnet/sdk:9.0 AS build
WORKDIR /src
COPY . .
RUN dotnet publish -c Release -o /app

FROM mcr.microsoft.com/dotnet/aspnet:9.0
WORKDIR /app
COPY --from=build /app .
ENTRYPOINT ["dotnet", "MyApi.dll"]

# Build and run
# docker build -t my-api .
# docker run -p 8080:8080 my-api

Distribuire su Azure App Service

Distribuisca direttamente su Azure App Service dalla CLI. Il servizio gestisce il ridimensionamento, i certificati e i domini personalizzati.

# Publish to folder first
dotnet publish -c Release -o ./publish

# Deploy to Azure App Service
az webapp up \
  --name my-products-api \
  --resource-group myRG \
  --runtime DOTNETCORE:9.0 \
  --sku B1

# View logs
az webapp log tail --name my-products-api --resource-group myRG

Controlli dello stato di salute

Aggiunga endpoint per i controlli dello stato di salute, così che gli orchestratori (Kubernetes, Azure) possano verificare che l'API sia attiva e pronta a gestire il traffico.

builder.Services.AddHealthChecks()
    .AddDbContextCheck<AppDbContext>()
    .AddUrlGroup(new Uri("https://api.external.com/ping"), "external");

app.MapHealthChecks("/health");
app.MapHealthChecks("/health/ready", new HealthCheckOptions
{
    Predicate = hc => hc.Tags.Contains("ready")
});

Esempio reale: checklist per la produzione

Una Minimal API destinata alla produzione dovrebbe includere queste impostazioni per garantire correttezza, osservabilità e sicurezza.

// builder configuration
builder.Services.AddProblemDetails();
builder.Services.AddHealthChecks();
builder.Services.AddRateLimiter(...);
builder.Services.AddOutputCache();

// app pipeline
app.UseHttpsRedirection();
app.UseExceptionHandler();
app.UseRateLimiter();
app.UseOutputCache();
app.UseAuthentication();
app.UseAuthorization();

app.MapHealthChecks("/health");
// ... your endpoints
app.Run();

Verifica rapida

Quale metodo rende visibili i metadati degli endpoint (Produces, WithSummary ecc.) agli strumenti OpenAPI nelle Minimal API?

Riepilogo: OpenAPI, versioning e distribuzione

Punti chiave:

AddEndpointsApiExplorer + Swashbuckle = Swagger UI per le Minimal API
Annoti gli endpoint con Produces, WithSummary e WithTags per una documentazione OpenAPI completa
Versioning semplice tramite gruppi di route; Asp.Versioning per scenari avanzati
Pubblicare un'immagine autonoma o Docker per una distribuzione flessibile
Aggiunga controlli dello stato di salute per i probe di disponibilità di Kubernetes/Azure

Domande Frequenti

La lezione «OpenAPI, versionamento e distribuzione» è gratuita?

Sì — il testo completo di «OpenAPI, versionamento e distribuzione» è 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 «OpenAPI, versionamento e distribuzione»?

Generi la documentazione Swagger/OpenAPI, versioni le API e distribuisca una Minimal API in Azure App Service o in container. 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 4 di 4.

Quanto tempo richiede la lezione «OpenAPI, versionamento e distribuzione»?

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