Action tipizzate in un controller Web API di ASP.NET Core 2.1

Swagger (https://swagger.io) è divenuto oramai lo standard de-facto per la documentazione di una RESTful API. ASP.NET supporta questo formato sin dalle prime versioni di Web API, grazie alla libreria open source Swashbuckle (https://github.com/domaindrivendev/Swashbuckle.AspNetCore).

In particolare, Swashbuckle.AspNetCore è il pacchetto che dobbiamo referenziare per aggiungere il supporto a Swagger a un progetto ASP.NET Core Web API. Possiamo installarlo tramite NuGet con il seguente comando:

Install-Package Swashbuckle.Aspnetcore

A questo punto, la configurarezione del servizio per la generazione del file json avviene all'interno della classe Startup:

public void ConfigureServices(IServiceCollection services)
{
    // .. altro codice qui ..

    services.AddSwaggerGen(c =>
    {
        c.SwaggerDoc("v1", new Info { Title = "My Sample API", Version = "v1" });
    });
}

Per esporre questo document in uno specifico endpoint, possiamo poi usare l'extension method UseSwagger:

public void Configure(IApplicationBuilder app, IHostingEnvironment env, DiagnosticListener listener)
{
    // .. altro codice qui ..

    app.UseSwagger();

    app.UseSwaggerUI(c =>
    {
        c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
    });

    app.UseHttpsRedirection();
    app.UseMvc();
}

Per default, la documentazione viene esposta all'indirizzo /swagger/v1/swagger.json.

Nel codice in alto, abbiamo anche usato UseSwaggerUI per esporre una pagina interattiva di help su /swagger/index.html.

Swashbuckle sfrutta appieno la nuova classe ActionResult<T> di ASP.NET Core 2.1, che abbiamo introdotto in uno script precedente (https://www.aspitalia.com/script/1300/Action-Tipizzate-Controller-Web-API-ASP.NET-Core-2.1.aspx), per mostrare informazioni dettagliate sui tipi restituiti dalle singole action: