Swagger Tools per documentare Api DotNet Core

Scrivere una buona documentazione per un API consente di comprenderne facilmente le funzionalità e le modalità di utilizzo. Spesso la riscrittura della documentazione viene effettuata manualmente. Esistono numerosi sistemi che consentono di automatizzare le operazioni di scrittura della documentazione: uno di questi è Swagger/OpenApi. A partire da una descrizione dell’ API, i tool automatici consentono di generare la documentazione completa.

I tool comunemente utilizzati sono basati su OpenApi, una specifica che consente di descrivere un’API, evidenziando :

• endpoint
• parametri delle operazioni
• metodi di autenticazione
• contatti e dettagli implementativi

La scrittura della documentazione avviene utilizzando JSON oppure YAML.

Swagger è costituito da una serie di strumenti che consentono di progettare, compilare e documentare le API. I tools presenti in Swagger utilizzano OpenAPI per compredere la struttura delle singole API. Tra i vari tools SwaggerUI consente di visualizzare all’interno di un browser la documentazione scritta in OpenAPI, mentre Swagger CodeGen consente di generare il codice del client.

Swashbuckle

Swashbuckle è un’implementazione open source di Swagger usata per la generazione di documentazione Swagger per le API .NET Core. E’ composto da tre elementi:

• Swashbuckle.AspNetCore.SwaggerGen: questo componente è il modello a oggetti e il middleware di Swagger per esporre oggetti SwaggerDocument come endpoint JSON
• Swashbuckle.AspNetCore.Swagger: questa raccolta è 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: questo pacchetto è una versione incorporata dello strumento Swagger UI. 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

Il primo steps per poter utilizzare Swashbuckle all’interno di un’applicazione ASP.NET Core esistente, è quello di aggiungere il suo riferimento alla soluzione:

> dotnet add package Swashbuckle.AspNetCore

e modificare il file Startup.cs aggiungendo all’inizio il riferimento alla libreria appena aggiunta al progetto:

using Swashbuckle.AspNetCore.Swagger;

Modificare il metodo ConfigureServices (sempre all’interno del file Startup.cs) aggiungendo:

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

e il metodo Configure aggiungendo:

    // 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 =>
    {
        c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
    });

per l’abilitazione del middleware e del relativo endpoint. Il file .json contentente la documentazione generata si troverà all’interno dell’url URL_SITO/swagger/v1/swagger.json, dove URL_SITO è il base URL del sito che sta deployando. La risposta che si ottiene nel browser questa volta è un documento che descrive gli endpoint dell’API .

Per poter visualizzare la documentazione in formato grafico (con la quale è possibile interagire) è possibile collegarsi a URL_SITO/swagger/index.html.

Personalizzare la documentazione generata, con i commenti in formato XML

Swagger mette a disposizione una serie di nodi xml che possono essere associati alle singole API in modo da fornire un maggiore dettaglio alla documentazione generata automaticamente. In particolare:

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

A questo punto le API sono state documentate in maniera automatica. In un prossimo post vedremo come procedere per la generazione automatica del client a partire proprio da questa documentazione.