Documentare un'API Web ASP.NET Core con gli strumenti di Swagger

  • 5 minuti

Un'API può avere un grande valore, ma se gli sviluppatori non sanno come usarla non avrà una grande diffusione. Gli sviluppatori devono integrare le API il più rapidamente possibile. Una buona documentazione relativa all'API consente allo sviluppatore di comprenderne le funzionalità e le modalità d'uso, rendendo l'integrazione più efficiente.

In passato la documentazione relativa alle API e a come usarle veniva redatta a mano. Ora è disponibile una specifica standard per le descrizioni API denominate OpenAPI. Swagger UI fornisce gli strumenti di implementazione e test della specifica OpenAPI per le API. Swashbuckle è un pacchetto open source che consente di generare automaticamente documenti di descrizione OpenAPI direttamente dai controller API Web usando la reflection .NET. Swashbuckle consente di automatizzare il processo di descrizione, semplificando la generazione, la gestione e l'uso della documentazione dell'API basata su OpenAPI da parte dei team. È sufficiente descrivere l'API e gli strumenti genereranno una documentazione completa.

OpenAPI

OpenAPI è una specifica usata per descrivere le API REST. È indipendente dal linguaggio di programmazione e consente di descrivere l'intera API, compresi gli elementi seguenti:

  • Endpoint disponibili
  • Parametri delle operazioni
  • Metodi di autenticazione
  • Contatti e altre informazioni

È possibile scrivere specifiche dell'API in YAML o JSON. Con la specifica OpenAPI sia le persone che i computer possono comprendere appieno le funzionalità dell'API senza dover accedere al relativo codice sorgente.

Swagger

Swagger è un set di strumenti open source compilati a partire dalla specifica OpenAPI. Questi strumenti consentono di progettare, compilare e documentare le API REST. Swagger usa la specifica OpenAPI dell'API per comprenderne la struttura.

Ad esempio, Swagger UI è uno strumento che può eseguire visivamente il rendering della documentazione in un browser per un'API definita con la specifica OpenAPI. Swagger Codegen può usare la stessa specifica OpenAPI dell'API e generare SDK dei client.

Swashbuckle

Swashbuckle è un'implementazione open source di Swagger usata per la generazione di documentazione Swagger per le API .NET Core tramite la reflection .NET.

Esistono tre componenti principali di Swashbuckle:

  • Swashbuckle.AspNetCore.Swagger: questo componente è il modello a oggetti e il middleware di Swagger per esporre oggetti SwaggerDocument come endpoint JSON.

  • Swashbuckle.AspNetCore.SwaggerGen: questa raccolta è un generatore Swagger che compila oggetti SwaggerDocument direttamente da route, controller e modelli. La libreria è combinata 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.

  • Interfaccia della riga di comando di Swashbuckle: Dopo l'installazione, questo strumento globale .NET consente di generare specifiche OpenAPI durante la compilazione/pubblicazione. Alla fine di questo modulo è disponibile un collegamento per scaricare Swashbuckle CLI.

Poiché queste librerie vengono aggiunte all'app, generano e consentono di visualizzare la documentazione della versione più recente dell'API. Viene creata documentazione dinamica, sempre sincronizzata con il codice più recente.