Introduzione a Swashbuckle e ad ASP.NET Core

Esistono tre componenti principali di Swashbuckle:

• Swashbuckle.AspNetCore.Swagger: un modello a oggetti Swagger e il middleware per esporre oggetti SwaggerDocument come endpoint JSON.

• Swashbuckle.AspNetCore.SwaggerGen: un generatore Swagger che compila oggetti SwaggerDocument direttamente da route, controller e modelli. È usato in genere con il middleware di endpoint di Swagger per esporre automaticamente i file JSON di Swagger.

• Swashbuckle.AspNetCore.SwaggerUI: una versione incorporata dello strumento interfaccia utente di Swagger, Interpreta i file JSON di Swagger per creare un'esperienza avanzata e personalizzabile per descrivere le funzionalità delle API Web. Include test harness predefiniti per i metodi pubblici.

Installazione del pacchetto

È possibile aggiungere Swashbuckle con gli approcci seguenti:

dotnet add TodoApi.csproj package Swashbuckle.AspNetCore -v 6.6.2

dotnet add TodoApi.csproj package Swashbuckle.AspNetCore -v 6.6.2

Aggiungere e configurare il middleware di Swagger

Aggiungere il generatore Swagger alla raccolta di servizi in Program.cs:

builder.Services.AddControllers();

builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

La chiamata a AddEndpointsApiExplorer illustrata nell'esempio precedente è necessaria solo per le API minime. Per altre informazioni, vedere questo post di StackOverflow.

Abilitare il middleware per la gestione del documento JSON generato e dell'interfaccia utente di Swagger, anche in Program.cs:

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

Il codice precedente aggiunge il middleware Swagger solo se l'ambiente corrente è impostato su Sviluppo. La UseSwaggerUI chiamata al metodo abilita una versione incorporata dello strumento dell'interfaccia utente di Swagger.

Avviare l'app e passare a https://localhost:<port>/swagger/v1/swagger.json. Il documento generato che descrive gli endpoint viene visualizzato come illustrato nella specifica OpenAPI (openapi.json).

L'interfaccia utente di Swagger è disponibile in https://localhost:<port>/swagger. Esplorare l'API tramite l'interfaccia utente di Swagger e incorporarla in altri programmi.

if (builder.Environment.IsDevelopment())
{
    app.UseSwaggerUI(options => // UseSwaggerUI is called only in Development.
    {
        options.SwaggerEndpoint("/swagger/v1/swagger.json", "v1");
        options.RoutePrefix = string.Empty;
    });
}

Se si usano le directory con ISS o il proxy inverso, impostare l'endpoint Swagger su un percorso relativo tramite il prefisso ./. Ad esempio: ./swagger/v1/swagger.json. L'uso di /swagger/v1/swagger.json indica all'app di cercare il file JSON nella vera radice dell'URL (con il prefisso della route, se usato). Usare, ad esempio, https://localhost:<port>/<route_prefix>/swagger/v1/swagger.json invece di https://localhost:<port>/<virtual_directory>/<route_prefix>/swagger/v1/swagger.json.

app.UseSwagger(options =>
{
    options.SerializeAsV2 = true;
});

Personalizzare ed estendere

Swagger offre opzioni per documentare il modello a oggetti e personalizzare l'interfaccia utente in modo che corrisponda al tema.

Informazioni e descrizione API

L'azione di configurazione passata al AddSwaggerGen metodo aggiunge informazioni quali l'autore, la licenza e la descrizione.

In Program.csimportare lo spazio dei nomi seguente per usare la OpenApiInfo classe :

using Microsoft.OpenApi.Models;

Usando la OpenApiInfo classe , modificare le informazioni visualizzate nell'interfaccia utente:

builder.Services.AddSwaggerGen(options =>
{
    options.SwaggerDoc("v1", new OpenApiInfo
    {
        Version = "v1",
        Title = "ToDo API",
        Description = "An ASP.NET Core Web API for managing ToDo items",
        TermsOfService = new Uri("https://example.com/terms"),
        Contact = new OpenApiContact
        {
            Name = "Example Contact",
            Url = new Uri("https://example.com/contact")
        },
        License = new OpenApiLicense
        {
            Name = "Example License",
            Url = new Uri("https://example.com/license")
        }
    });
});

L'interfaccia utente di Swagger visualizza le informazioni sulla versione:

Commenti in XML

I commenti XML possono essere abilitati con gli approcci seguenti:

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>

Abilitando i commenti XML, viene eseguito il debug delle informazioni per membri e tipi pubblici non documentati. I membri e tipi non documentati sono indicati nel messaggio di avviso. Ad esempio, il messaggio seguente indica una violazione del codice di avviso 1591:

warning CS1591: Missing XML comment for publicly visible type or member 'TodoController'

Per eliminare gli avvisi per l'intero progetto, definire un elenco delimitato da punto e virgola di codici di avviso da ignorare nel file di progetto. L'aggiunta di codici di avviso a $(NoWarn); applica anche i valori predefiniti di C#.

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
  <NoWarn>$(NoWarn);1591</NoWarn>
</PropertyGroup>

Per eliminare gli avvisi solo per membri specifici, racchiudere il codice in direttive del preprocessore #pragma warning. Questo approccio è utile per il codice che non deve essere esposto tramite la documentazione dell'API. Nell'esempio seguente il codice di avviso CS1591 viene ignorato per l'intera TodoContext classe. L'imposizione del codice di avviso viene ripristinata alla chiusura della definizione della classe. Specificare più codici di avviso con un elenco delimitato da virgole.

namespace SwashbuckleSample.Models;

#pragma warning disable CS1591
public class TodoContext : DbContext
{
    public TodoContext(DbContextOptions<TodoContext> options) : base(options) { }

    public DbSet<TodoItem> TodoItems => Set<TodoItem>();
}
#pragma warning restore CS1591

Configurare Swagger per usare il file XML che viene generato con le istruzioni precedenti. Per Linux o sistemi operativi diversi da Windows, i percorsi e i nomi di file possono fare distinzione tra maiuscole e minuscole. Ad esempio, un TodoApi.XML file è valido in Windows ma non in Ubuntu.

builder.Services.AddSwaggerGen(options =>
{
    options.SwaggerDoc("v1", new OpenApiInfo
    {
        Version = "v1",
        Title = "ToDo API",
        Description = "An ASP.NET Core Web API for managing ToDo items",
        TermsOfService = new Uri("https://example.com/terms"),
        Contact = new OpenApiContact
        {
            Name = "Example Contact",
            Url = new Uri("https://example.com/contact")
        },
        License = new OpenApiLicense
        {
            Name = "Example License",
            Url = new Uri("https://example.com/license")
        }
    });

    // using System.Reflection;
    var xmlFilename = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
    options.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, xmlFilename));
});

Nel codice precedente la reflection consente di compilare un nome file XML che corrisponde a quello del progetto API Web. La proprietà AppContext.BaseDirectory viene usata per costruire un percorso del file XML. Alcune funzionalità di Swagger (ad esempio, schemi di parametri di input o i metodi HTTP e i codici di risposta dai rispettivi attributi) funzionano senza l'uso di un file di documentazione XML. Per la maggior parte delle funzionalità, vale a dire i riepiloghi dei metodi e le descrizioni dei parametri e dei codici di risposta, l'uso di un file XML è obbligatorio.

Se si aggiungono commenti con barra tripla a un'azione si migliora Swagger UI aggiungendo la descrizione all'intestazione della sezione. Aggiungere un <elemento di riepilogo> sopra l'azione Delete :

/// <summary>
/// Deletes a specific TodoItem.
/// </summary>
/// <param name="id"></param>
/// <returns></returns>
[HttpDelete("{id}")]
public async Task<IActionResult> Delete(long id)
{
    var item = await _context.TodoItems.FindAsync(id);

    if (item is null)
    {
        return NotFound();
    }

    _context.TodoItems.Remove(item);
    await _context.SaveChangesAsync();

    return NoContent();
}

L'interfaccia utente di Swagger visualizza il testo interno dell'elemento <summary> del codice precedente:

L'interfaccia utente è determinata dallo schema JSON generato:

"delete": {
    "tags": [
        "Todo"
    ],
    "summary": "Deletes a specific TodoItem.",
    "parameters": [
        {
            "name": "id",
            "in": "path",
            "description": "",
            "required": true,
            "schema": {
                "type": "integer",
                "format": "int64"
            }
        }
    ],
    "responses": {
        "200": {
            "description": "Success"
        }
    }
},

Aggiungere un <elemento osservazioni> alla documentazione del Create metodo di azione. In questo modo vengono integrate le informazioni specificate nell'elemento <summary> e l'interfaccia utente di Swagger risulta più affidabile. Il contenuto dell'elemento <remarks> può essere costituito da testo, JSON o XML.

/// <summary>
/// Creates a TodoItem.
/// </summary>
/// <param name="item"></param>
/// <returns>A newly created TodoItem</returns>
/// <remarks>
/// Sample request:
///
///     POST /Todo
///     {
///        "id": 1,
///        "name": "Item #1",
///        "isComplete": true
///     }
///
/// </remarks>
/// <response code="201">Returns the newly created item</response>
/// <response code="400">If the item is null</response>
[HttpPost]
[ProducesResponseType(StatusCodes.Status201Created)]
[ProducesResponseType(StatusCodes.Status400BadRequest)]
public async Task<IActionResult> Create(TodoItem item)
{
    _context.TodoItems.Add(item);
    await _context.SaveChangesAsync();

    return CreatedAtAction(nameof(Get), new { id = item.Id }, item);
}

Si notino i miglioramenti dell'interfaccia utente con questi commenti aggiuntivi:

Annotazioni dei dati

Contrassegnare il modello con gli attributi, disponibili nello spazio dei nomi, per facilitare l'unità dei componenti dell'interfaccia System.ComponentModel.DataAnnotations utente di Swagger.

Aggiungere l'attributo [Required] alla proprietà Name della classe TodoItem:

using System.ComponentModel;
using System.ComponentModel.DataAnnotations;

namespace SwashbuckleSample.Models;

public class TodoItem
{
    public long Id { get; set; }

    [Required]
    public string Name { get; set; } = null!;

    [DefaultValue(false)]
    public bool IsComplete { get; set; }
}

La presenza di questo attributo modifica il comportamento dell'interfaccia utente e lo schema JSON sottostante:

"schemas": {
    "TodoItem": {
        "required": [
            "name"
        ],
        "type": "object",
        "properties": {
            "id": {
                "type": "integer",
                "format": "int64"
            },
            "name": {
                "type": "string"
            },
            "isComplete": {
                "type": "boolean",
                "default": false
            }
        },
        "additionalProperties": false
    }
},

Aggiungere l'attributo [Produces("application/json")] al controller API. Il suo scopo consiste nel dichiarare che le azioni del controller supportano un tipo di contenuto della risposta di application/json:

[ApiController]
[Route("api/[controller]")]
[Produces("application/json")]
public class TodoController : ControllerBase
{

L'elenco a discesa Tipo di supporto seleziona questo tipo di contenuto come predefinito per le azioni GET del controller:

Con l'aumento dell'uso delle annotazioni dei dati nell'API Web, le pagine della Guida dell'API e dell'interfaccia utente diventano più descrittive e utili.

Descrivere i tipi di risposta

Gli sviluppatori che usano un'API Web sono maggiormente interessati a ciò che viene restituito, in particolare ai tipi di risposta e ai codici di errore (se non standard). I tipi di risposta e i codici di errore vengono indicati nei commenti XML e nelle annotazioni dei dati.

L'azione Create restituisce un codice di stato HTTP 201 in caso di esito positivo. Quando il corpo della richiesta inviata è Null, viene restituito un codice di stato HTTP 400. Senza la documentazione appropriata nell'interfaccia utente di Swagger, il consumer non riconosce tali risultati previsti. Risolvere il problema aggiungendo le righe evidenziate nell'esempio seguente:

/// <summary>
/// Creates a TodoItem.
/// </summary>
/// <param name="item"></param>
/// <returns>A newly created TodoItem</returns>
/// <remarks>
/// Sample request:
///
///     POST /Todo
///     {
///        "id": 1,
///        "name": "Item #1",
///        "isComplete": true
///     }
///
/// </remarks>
/// <response code="201">Returns the newly created item</response>
/// <response code="400">If the item is null</response>
[HttpPost]
[ProducesResponseType(StatusCodes.Status201Created)]
[ProducesResponseType(StatusCodes.Status400BadRequest)]
public async Task<IActionResult> Create(TodoItem item)
{
    _context.TodoItems.Add(item);
    await _context.SaveChangesAsync();

    return CreatedAtAction(nameof(Get), new { id = item.Id }, item);
}

L'interfaccia utente di Swagger ora documenta chiaramente i codici di risposta HTTP previsti:

Le convenzioni possono essere usate come alternativa per decorare in modo esplicito le singole azioni con [ProducesResponseType]. Per altre informazioni, vedere Usare le convenzioni dell'API Web.

Per supportare la [ProducesResponseType] decorazione, il pacchetto Swashbuckle.AspNetCore.Annotations offre estensioni per abilitare e arricchire la risposta, lo schema e i metadati dei parametri.

Personalizzare l'interfaccia utente

L'interfaccia utente predefinita è funzionale e presentabile. ma è necessario che le pagine della documentazione API rappresentino il proprio marchio o tema. Per personalizzare i componenti Swashbuckle è necessario aggiungere le risorse per gestire i file statici e quindi compilare la struttura di cartelle per ospitare i file.

Abilitare il middleware dei file statici:

app.UseHttpsRedirection();
app.UseStaticFiles();
app.MapControllers();

Per inserire fogli di stile CSS aggiuntivi, aggiungerli alla cartella wwwroot del progetto e specificare il percorso relativo nelle opzioni middleware:

if (app.Environment.IsDevelopment())
{
    app.UseSwaggerUI(options => // UseSwaggerUI is called only in Development.
    {
        options.InjectStylesheet("/swagger-ui/custom.css");
    });
}

Risorse aggiuntive

• Visualizzare o scaricare il codice di esempio (procedura per il download)
• Migliorare l'esperienza di sviluppo di un'API con la documentazione di Swagger

Visualizzare o scaricare il codice di esempio (procedura per il download)

Esistono tre componenti principali di Swashbuckle:

• Swashbuckle.AspNetCore.Swagger: un modello a oggetti Swagger e il middleware per esporre oggetti SwaggerDocument come endpoint JSON.

• Swashbuckle.AspNetCore.SwaggerGen: un generatore Swagger che compila oggetti SwaggerDocument direttamente da route, controller e modelli. È usato in genere con il middleware di endpoint di Swagger per esporre automaticamente i file JSON di Swagger.

• Swashbuckle.AspNetCore.SwaggerUI: una versione incorporata dello strumento interfaccia utente di Swagger, Interpreta i file JSON di Swagger per creare un'esperienza avanzata e personalizzabile per descrivere le funzionalità delle API Web. Include test harness predefiniti per i metodi pubblici.

Installazione del pacchetto

È possibile aggiungere Swashbuckle con gli approcci seguenti:

dotnet add TodoApi.csproj package Swashbuckle.AspNetCore -v 5.6.3

dotnet add TodoApi.csproj package Swashbuckle.AspNetCore -v 5.6.3

Aggiungere e configurare il middleware di Swagger

Aggiungere il generatore di Swagger alla raccolta di servizi nel metodo Startup.ConfigureServices:

public void ConfigureServices(IServiceCollection services)
{
    services.AddDbContext<TodoContext>(opt =>
        opt.UseInMemoryDatabase("TodoList"));
    services.AddControllers();

    // Register the Swagger generator, defining 1 or more Swagger documents
    services.AddSwaggerGen();
}

Nel metodo Startup.Configure abilitare il middleware per la gestione del documento JSON generato e l'interfaccia utente di Swagger:

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        // Enable middleware to serve generated Swagger as a JSON endpoint.
        app.UseSwagger();

        // Enable middleware to serve swagger-ui (HTML, JS, CSS, etc.)
        app.UseSwaggerUI();
    }

    app.UseRouting();
    app.UseEndpoints(endpoints =>
    {
        endpoints.MapControllers();
    });
}

In fase di sviluppo, la chiamata al metodo precedente UseSwaggerUI abilita una versione incorporata dello strumento dell'interfaccia utente di Swagger. Questo dipende dal middleware dei file statici. Se si usa .NET Framework o .NET Core 1.x, aggiungere il pacchetto NuGet Microsoft.AspNetCore.StaticFiles al progetto.

Avviare l'app e passare a http://localhost:<port>/swagger/v1/swagger.json. Il documento generato che descrive gli endpoint viene visualizzato come illustrato nella specifica OpenAPI (openapi.json).

L'interfaccia utente di Swagger è disponibile in http://localhost:<port>/swagger. Esplorare l'API tramite l'interfaccia utente di Swagger e incorporarla in altri programmi.

// // UseSwaggerUI Protected by if (env.IsDevelopment())
app.UseSwaggerUI(c => // UseSwaggerUI Protected by if (env.IsDevelopment())
{
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
    c.RoutePrefix = string.Empty;
});

Se si usano le directory con ISS o il proxy inverso, impostare l'endpoint Swagger su un percorso relativo tramite il prefisso ./. Ad esempio: ./swagger/v1/swagger.json. L'uso di /swagger/v1/swagger.json indica all'app di cercare il file JSON nella vera radice dell'URL (con il prefisso della route, se usato). Usare, ad esempio, http://localhost:<port>/<route_prefix>/swagger/v1/swagger.json invece di http://localhost:<port>/<virtual_directory>/<route_prefix>/swagger/v1/swagger.json.

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        // Enable middleware to serve generated Swagger as a JSON endpoint.
        app.UseSwagger(c =>
        {
            c.SerializeAsV2 = true;
        });

        // Enable middleware to serve swagger-ui (HTML, JS, CSS, etc.),
        // specifying the Swagger JSON endpoint.
        // UseSwaggerUI is called only in Development.
        app.UseSwaggerUI(c => // UseSwaggerUI Protected by if (env.IsDevelopment())
        {
            c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
        });
    }

    app.UseRouting();
    app.UseEndpoints(endpoints =>
    {
        endpoints.MapControllers();
    });
}

Personalizzare ed estendere

Swagger offre opzioni per documentare il modello a oggetti e personalizzare l'interfaccia utente in modo che corrisponda al tema.

Nella classe Startup aggiungere gli spazi dei nomi seguenti:

using System;
using System.Reflection;
using System.IO;

Informazioni e descrizione API

L'azione di configurazione passata al metodo AddSwaggerGen aggiunge informazioni come ad esempio autore, licenza e descrizione:

Nella classe Startup importare gli spazi dei nomi seguenti per usare la classe OpenApiInfo:

using Microsoft.OpenApi.Models;

Usando la OpenApiInfo classe , modificare le informazioni visualizzate nell'interfaccia utente:

// Register the Swagger generator, defining 1 or more Swagger documents
services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo
    {
        Version = "v1",
        Title = "ToDo API",
        Description = "A simple example ASP.NET Core Web API",
        TermsOfService = new Uri("https://example.com/terms"),
        Contact = new OpenApiContact
        {
            Name = "Shayne Boyer",
            Email = string.Empty,
            Url = new Uri("https://twitter.com/spboyer"),
        },
        License = new OpenApiLicense
        {
            Name = "Use under LICX",
            Url = new Uri("https://example.com/license"),
        }
    });
});

L'interfaccia utente di Swagger visualizza le informazioni sulla versione:

Commenti in XML

I commenti XML possono essere abilitati con gli approcci seguenti:

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
  <NoWarn>$(NoWarn);1591</NoWarn>
</PropertyGroup>

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
  <NoWarn>$(NoWarn);1591</NoWarn>
</PropertyGroup>

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
  <NoWarn>$(NoWarn);1591</NoWarn>
</PropertyGroup>

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
  <NoWarn>$(NoWarn);1591</NoWarn>
</PropertyGroup>

Abilitando i commenti XML, viene eseguito il debug delle informazioni per membri e tipi pubblici non documentati. I membri e tipi non documentati sono indicati nel messaggio di avviso. Ad esempio, il messaggio seguente indica una violazione del codice di avviso 1591:

warning CS1591: Missing XML comment for publicly visible type or member 'TodoController.GetAll()'

Per eliminare gli avvisi per l'intero progetto, definire un elenco delimitato da punto e virgola di codici di avviso da ignorare nel file di progetto. L'aggiunta di codici di avviso a $(NoWarn); applica anche i valori predefiniti di C#.

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
  <NoWarn>$(NoWarn);1591</NoWarn>
</PropertyGroup>

Per eliminare gli avvisi solo per membri specifici, racchiudere il codice in direttive del preprocessore #pragma warning. Questo approccio è utile per il codice che non deve essere esposto tramite la documentazione dell'API. Nell'esempio seguente il codice di avviso CS1591 viene ignorato per l'intera Program classe. L'imposizione del codice di avviso viene ripristinata alla chiusura della definizione della classe. Specificare più codici di avviso con un elenco delimitato da virgole.

namespace TodoApi
{
#pragma warning disable CS1591
    public class Program
    {
        public static void Main(string[] args) =>
            BuildWebHost(args).Run();

        public static IWebHost BuildWebHost(string[] args) =>
            WebHost.CreateDefaultBuilder(args)
                .UseStartup<Startup>()
                .Build();
    }
#pragma warning restore CS1591
}

Configurare Swagger per usare il file XML che viene generato con le istruzioni precedenti. Per Linux o sistemi operativi diversi da Windows, i percorsi e i nomi di file possono fare distinzione tra maiuscole e minuscole. Ad esempio, un TodoApi.XML file è valido in Windows ma non in Ubuntu.

public void ConfigureServices(IServiceCollection services)
{
    services.AddDbContext<TodoContext>(opt =>
        opt.UseInMemoryDatabase("TodoList"));
    services.AddControllers();

    // Register the Swagger generator, defining 1 or more Swagger documents
    services.AddSwaggerGen(c =>
    {
        c.SwaggerDoc("v1", new OpenApiInfo
        {
            Version = "v1",
            Title = "ToDo API",
            Description = "A simple example ASP.NET Core Web API",
            TermsOfService = new Uri("https://example.com/terms"),
            Contact = new OpenApiContact
            {
                Name = "Shayne Boyer",
                Email = string.Empty,
                Url = new Uri("https://twitter.com/spboyer"),
            },
            License = new OpenApiLicense
            {
                Name = "Use under LICX",
                Url = new Uri("https://example.com/license"),
            }
        });

        // Set the comments path for the Swagger JSON and UI.
        var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
        var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
        c.IncludeXmlComments(xmlPath);
    });
}

Nel codice precedente la reflection consente di compilare un nome file XML che corrisponde a quello del progetto API Web. La proprietà AppContext.BaseDirectory viene usata per costruire un percorso del file XML. Alcune funzionalità di Swagger (ad esempio, schemi di parametri di input o i metodi HTTP e i codici di risposta dai rispettivi attributi) funzionano senza l'uso di un file di documentazione XML. Per la maggior parte delle funzionalità, vale a dire i riepiloghi dei metodi e le descrizioni dei parametri e dei codici di risposta, l'uso di un file XML è obbligatorio.

Se si aggiungono commenti con barra tripla a un'azione si migliora Swagger UI aggiungendo la descrizione all'intestazione della sezione. Aggiungere un <elemento di riepilogo> sopra l'azione Delete :

/// <summary>
/// Deletes a specific TodoItem.
/// </summary>
/// <param name="id"></param>        
[HttpDelete("{id}")]
public IActionResult Delete(long id)
{
    var todo = _context.TodoItems.Find(id);

    if (todo == null)
    {
        return NotFound();
    }

    _context.TodoItems.Remove(todo);
    _context.SaveChanges();

    return NoContent();
}

L'interfaccia utente di Swagger visualizza il testo interno dell'elemento <summary> del codice precedente:

L'interfaccia utente è determinata dallo schema JSON generato:

"delete": {
    "tags": [
        "Todo"
    ],
    "summary": "Deletes a specific TodoItem.",
    "operationId": "ApiTodoByIdDelete",
    "consumes": [],
    "produces": [],
    "parameters": [
        {
            "name": "id",
            "in": "path",
            "description": "",
            "required": true,
            "type": "integer",
            "format": "int64"
        }
    ],
    "responses": {
        "200": {
            "description": "Success"
        }
    }
}

Aggiungere un <elemento osservazioni> alla documentazione del Create metodo di azione. In questo modo vengono integrate le informazioni specificate nell'elemento <summary> e l'interfaccia utente di Swagger risulta più affidabile. Il contenuto dell'elemento <remarks> può essere costituito da testo, JSON o XML.

/// <summary>
/// Creates a TodoItem.
/// </summary>
/// <remarks>
/// Sample request:
///
///     POST /Todo
///     {
///        "id": 1,
///        "name": "Item1",
///        "isComplete": true
///     }
///
/// </remarks>
/// <param name="item"></param>
/// <returns>A newly created TodoItem</returns>
/// <response code="201">Returns the newly created item</response>
/// <response code="400">If the item is null</response>            
[HttpPost]
[ProducesResponseType(StatusCodes.Status201Created)]
[ProducesResponseType(StatusCodes.Status400BadRequest)]
public ActionResult<TodoItem> Create(TodoItem item)
{
    _context.TodoItems.Add(item);
    _context.SaveChanges();

    return CreatedAtRoute("GetTodo", new { id = item.Id }, item);
}

Si notino i miglioramenti dell'interfaccia utente con questi commenti aggiuntivi:

Annotazioni dei dati

Contrassegnare il modello con gli attributi, disponibili nello spazio dei nomi, per facilitare l'unità dei componenti dell'interfaccia System.ComponentModel.DataAnnotations utente di Swagger.

Aggiungere l'attributo [Required] alla proprietà Name della classe TodoItem:

using System.ComponentModel;
using System.ComponentModel.DataAnnotations;

namespace TodoApi.Models
{
    public class TodoItem
    {
        public long Id { get; set; }

        [Required]
        public string Name { get; set; }

        [DefaultValue(false)]
        public bool IsComplete { get; set; }
    }
}

La presenza di questo attributo modifica il comportamento dell'interfaccia utente e lo schema JSON sottostante:

"definitions": {
    "TodoItem": {
        "required": [
            "name"
        ],
        "type": "object",
        "properties": {
            "id": {
                "format": "int64",
                "type": "integer"
            },
            "name": {
                "type": "string"
            },
            "isComplete": {
                "default": false,
                "type": "boolean"
            }
        }
    }
},

Aggiungere l'attributo [Produces("application/json")] al controller API. Il suo scopo consiste nel dichiarare che le azioni del controller supportano un tipo di contenuto della risposta di application/json:

[Produces("application/json")]
[Route("api/[controller]")]
[ApiController]
public class TodoController : ControllerBase
{
    private readonly TodoContext _context;

L'elenco a discesa Response Content Type (Tipo di contenuto risposta) include questo tipo di contenuto come selezione predefinita per le azioni GET del controller:

Con l'aumento dell'uso delle annotazioni dei dati nell'API Web, le pagine della Guida dell'API e dell'interfaccia utente diventano più descrittive e utili.

Descrivere i tipi di risposta

Gli sviluppatori che usano un'API Web sono maggiormente interessati a ciò che viene restituito, in particolare ai tipi di risposta e ai codici di errore (se non standard). I tipi di risposta e i codici di errore vengono indicati nei commenti XML e nelle annotazioni dei dati.

L'azione Create restituisce un codice di stato HTTP 201 in caso di esito positivo. Quando il corpo della richiesta inviata è Null, viene restituito un codice di stato HTTP 400. Senza la documentazione appropriata nell'interfaccia utente di Swagger, il consumer non riconosce tali risultati previsti. Risolvere il problema aggiungendo le righe evidenziate nell'esempio seguente:

/// <summary>
/// Creates a TodoItem.
/// </summary>
/// <remarks>
/// Sample request:
///
///     POST /Todo
///     {
///        "id": 1,
///        "name": "Item1",
///        "isComplete": true
///     }
///
/// </remarks>
/// <param name="item"></param>
/// <returns>A newly created TodoItem</returns>
/// <response code="201">Returns the newly created item</response>
/// <response code="400">If the item is null</response>            
[HttpPost]
[ProducesResponseType(StatusCodes.Status201Created)]
[ProducesResponseType(StatusCodes.Status400BadRequest)]
public ActionResult<TodoItem> Create(TodoItem item)
{
    _context.TodoItems.Add(item);
    _context.SaveChanges();

    return CreatedAtRoute("GetTodo", new { id = item.Id }, item);
}

L'interfaccia utente di Swagger ora documenta chiaramente i codici di risposta HTTP previsti:

In ASP.NET Core 2.2 o versioni successive, possono essere usate convenzioni in alternativa alla decorazione esplicita di azioni singole con [ProducesResponseType]. Per altre informazioni, vedere Usare le convenzioni dell'API Web.

Per supportare la [ProducesResponseType] decorazione, il pacchetto Swashbuckle.AspNetCore.Annotations offre estensioni per abilitare e arricchire la risposta, lo schema e i metadati dei parametri.

Personalizzare l'interfaccia utente

L'interfaccia utente predefinita è funzionale e presentabile. ma è necessario che le pagine della documentazione API rappresentino il proprio marchio o tema. Per personalizzare i componenti Swashbuckle è necessario aggiungere le risorse per gestire i file statici e quindi compilare la struttura di cartelle per ospitare i file.

Se si usa .NET Framework o .NET Core 1.x, aggiungere il pacchetto NuGet Microsoft.AspNetCore.StaticFiles al progetto:

<PackageReference Include="Microsoft.AspNetCore.StaticFiles" Version="2.1.1" />

Il pacchetto NuGet precedente è già installato se si usano .NET Core 2.x e il metapackage.

Abilitare il middleware dei file statici:

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    app.UseStaticFiles();

    if (env.IsDevelopment())
    {
        // Enable middleware to serve generated Swagger as a JSON endpoint.
        app.UseSwagger();

        // Enable middleware to serve swagger-ui (HTML, JS, CSS, etc.),
        // specifying the Swagger JSON endpoint.
        app.UseSwaggerUI(c => // UseSwaggerUI Protected by if (env.IsDevelopment())
        {
            c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
        });
    }

    app.UseRouting();
    app.UseEndpoints(endpoints =>
    {
        endpoints.MapControllers();
    });
}

Per inserire fogli di stile CSS aggiuntivi, aggiungerli alla cartella wwwroot del progetto e specificare il percorso relativo nelle opzioni middleware:

if (env.IsDevelopment())
{
    app.UseSwaggerUI(c =>
    {
        c.InjectStylesheet("/swagger-ui/custom.css");
    }
}

Risorse aggiuntive

• Migliorare l'esperienza di sviluppo di un'API con la documentazione di Swagger