Completare la documentazione OpenAPI con commenti e annotazioni XML

Completato

L'interfaccia utente di Swagger consente di visualizzare e di interagire con le risorse di un'API senza dover accedere al relativo codice sorgente. La rappresentazione grafica dell'API viene generata automaticamente dalla specifica OpenAPI, semplificando così il compito degli altri sviluppatori che dovranno creare app usando le API.

L'interfaccia utente di Swagger visualizza le operazioni e i metodi in modo chiaro, come illustrato nell'immagine seguente.

L'interfaccia utente di Swagger consente inoltre di interagire con ogni operazione e persino di provarla.

La creazione automatica della documentazione dell'API con gli strumenti di Swashbuckle e Swagger può aiutare gli altri sviluppatori a capire le risorse dell'API. Ma è anche possibile andare oltre e specificare altre informazioni. Se si usa un'API per la prima volta, è opportuno avere quante più informazioni possibili.

Commenti in XML

È possibile creare la documentazione relativa al codice includendo commenti in formato XML. In genere i commenti vanno posizionati direttamente prima del blocco di codice cui si riferiscono.

/// <summary>
/// Returns a group of Employees matching the given first and last names.
/// </summary>
/// <remarks>
/// Here is a sample remarks placeholder.
/// </remarks>
/// <param name="firstName">The first name to search for</param>
/// <param name="lastName">The last name to search for</param>
/// <returns>A string status</returns>
[HttpGet]
[Route("byname/{firstName}/{lastName}")]
public ActionResult<string> GetByName(string firstName, string lastName)
{
    return "Found another University employee";
}

I nodi XML in uso sono i seguenti:

• riepilogo: riepilogo generale di metodo/classe/campo e della funzione relativa.
• Commenti: dettagli aggiuntivi su metodo/classe/campo.
• param: parametro del metodo e ciò che rappresenta.
• returns: descrizione di ciò che il metodo restituisce.

Dopo aver abilitato i commenti XML, lo strumento Swashbuckle può includere i commenti della documentazione XML nella documentazione di OpenAPI e te ne consente la visualizzazione nell'interfaccia utente di Swagger.

Annotazioni dei dati

La stessa cosa vale per le annotazioni dei dati. Aggiungi un'annotazione al tuo modello e Swagger estenderà la documentazione dell'API in modo da includerla.

Ad esempio, se si aggiunge l'annotazione seguente a un controller:

[Produces("application/json")]

... noti che l'informazione è stata aggiunta nell'interfaccia utente di Swagger:

Suggerimenti

Sono disponibili diverse annotazioni dei dati da usare quando si descrive l'API.

• Identificare quali content-types sono gestiti dall’API per le richieste e le risposte. Gli attributi seguenti specificano che l'API deve usare solo il tipo di contenuto application/json in entrambe le direzioni.

  [Produces("application/json")]
  [Consumes("application/json")]
  

• Identificare i potenziali codici di risposta HTTP che possono essere restituiti al client chiamante. L'attributo seguente illustra un'API che potrebbe restituire un errore "404 Non trovato".

  [ProducesResponseType(StatusCodes.Status404NotFound)]
  

  L'API può produrre un set standard di codici di risposta; in questo caso puoi usare l'attributo seguente per specificare 200, 400 e 404 invece di specificarli singolarmente. Altre informazioni sull'uso delle convenzioni dell'API Web.

  [ApiConventionMethod(typeof(DefaultApiConventions))]
  

• Generare un operationId per migliorare significativamente l'utilizzo dell'API, incluse documentazione, generazione di codice e integrazione con altri servizi. È possibile generare automaticamente l'oggetto operationId includendo la proprietà Name nel filtro del verbo HTTP.

  [HttpGet("{Height}/{Width}", Name="GetPrice")]