dotnet_core_swagger

Dotnet Core – Documentazione con Swagger

Scrivere la documentazione delle API di un’applicazione è spesso considerata un’operazione dispendiosa in termini di risorse e tempo. Nel corso degli anni sono stati sviluppati numerosi tools che consentono di creare la documentazione a partire dal codice sorgente, in maniera più o meno automatica.

Swagger  è uno di questi tools, perfettamente integrato in .NET e .NET Core, molto utilizzato per la documentazione di API, e disponibile tramite nuget. La generazione della documentazione, richiede un passaggio intermedio: la generazione della documentazione in formato xml al momento della build o del publish del progetto. 

Per poter abilitare la generazione della documentazione è necessario aggiungere il seguente codice all’interno del file .csproj dell’applicazione: 

A questo punto, all’interno della cartella bin verrà generata la documentazione in formato XML all’interno del file PROGETTO.XML. Nella configurazione è stata aggiunta la riga con il parametro NoWarn che indica al compilatore di non considerare gli eventuali warning con codice 1591, che corrispondono alle action/controller che non hanno documentazione. 

Siamo pronti ler lo scaricamento del pacchetto Swashbuckle il tool che consente di creare la documentazione per Swagger:

La configurazione del servizio Swashbuckle avviene all’interno del file Startup.cs, in particolare nel metodo ConfigureServices. Per poter utilizzare Swashbuckle è, infatti, necessario effettuare la registrazione del services, e configurarne alcuni parametri: 

E’ da notare l’attribuzione del percorso del file della documentazione includendola tramite il metodo IncludeXmlComments(…), dalla riga 7 alla riga 9.

Dopo aver configurato il progetto per la generazione del file xml, contenente la documentazione, al momento della build/publish, e il servizio all’interno del file Startup.cs, è necessario aggiungere alla pipeline dell’applicazione Swagger. All’interno del metodo Configure(…) del file Startup.cs è necessario aggiungere il seguente codice: 

Il codice precedente consente di aggiungere il nuovo end-point che rispondere alle chiamate (“/swagger”) all’interno del quale troveremo il file swagger.json. Perchè tutto funzioni correttamente è necessario abilitare anche l’utilizzo dei file statici nel seguente modo: 

Ovviamente è necessario documentare le Action dei nostri Controller utilizzando la convenzione utilizzata da .NET consultabile al link  e i commenti aggiunti direttamente da swagger. 

Un’ultima considerazione riguarda la documentazione: swagger consente di generare la documentazione di API: è quindi necessario attribuire a ciascuna action l’indicazione del VERB a cui corrisponde, ad esempio: 

I controller/action che non riportano questa indicazione, non verranno visualizzati nella documentazione. 

Concludendo, l’utilizzo di Swagger consente di generare in maniera automatica la documentazione delle API, al netto di una prima fase di configurazione. 

Pubblicato da

Andrea Merlin

Laureato in informatica, diversi corsi di specializzazione legati allo Sviluppo Software e alla Computer forensics. Appassionato di nuove tecnologie, amo la programmazione, la Business Intelligence e tematiche legate alla Privacy.Sempre alla ricerca di nuove idee, stimoli … e progetti da seguire!Amo trascorrere il tempo libero in Val Borbera, un piccolo angolo del Piemonte, in provincia di Alessandria.