Swagger: svi­lup­pa­re API più co­mo­da­men­te

La creazione della do­cu­men­ta­zio­ne è una delle parti che richiede più tempo nei progetti di sviluppo di ap­pli­ca­zio­ni web e, spesso, chi non è coinvolto in questo processo fatica a com­pren­der­ne l’im­por­tan­za per la ma­nu­ten­zio­ne e l’ulteriore sviluppo dei sistemi. Il valore di questo processo, però, risulta evidente so­prat­tut­to nel momento in cui un gruppo esterno a quello di sviluppo tenta di ef­fet­tua­re la ma­nu­ten­zio­ne e apportare migliorie all’ap­pli­ca­zio­ne, una pratica molto diffusa.

La do­cu­men­ta­zio­ne delle API, cioè delle Ap­pli­ca­tion Pro­gram­ming In­ter­fa­ces o in­ter­fac­ce di pro­gram­ma­zio­ne delle ap­pli­ca­zio­ni, riveste un ruolo ancora più im­por­tan­te. Le API servono a collegare le ap­pli­ca­zio­ni tra loro e a in­te­grar­le con fonti di dati e altri sistemi. La quasi totalità delle ap­pli­ca­zio­ni che si uti­liz­za­no quo­ti­dia­na­men­te si serve di una mol­ti­tu­di­ne di API che svolgono un ruolo centrale nelle con­nes­sio­ni software. Tuttavia, per poter uti­liz­za­re queste in­ter­fac­ce, bisogna anche co­no­scer­ne la struttura e le funzioni. Ciò è reso possibile dalla specifica OpenAPI Swagger, il formato di de­scri­zio­ne aperto grazie al quale è possibile tenere traccia delle diverse fun­zio­na­li­tà delle API. Swagger consente di stan­dar­diz­za­re i processi di do­cu­men­ta­zio­ne, rendendo la creazione delle API possibile anche per chi non ha preso parte al processo di sviluppo, grazie alla con­di­vi­sio­ne delle in­ter­fac­ce uti­liz­za­te e alla pos­si­bi­li­tà di do­cu­men­tar­le fin da subito.

In passato, la de­scri­zio­ne delle API risultava molto complessa a causa delle diverse tec­no­lo­gie impiegate e degli al­tret­tan­to diversi linguaggi di pro­gram­ma­zio­ne. Un primo im­por­tan­te passo verso un sistema più regolare si è compiuto quando REST è diventato il modello di pro­gram­ma­zio­ne per lo sviluppo delle API. Siti web come Google, Amazon e Twitter uti­liz­za­no API RESTful. Pre­ce­den­te­men­te, le in­ter­fac­ce di pro­gram­ma­zio­ne venivano descritte uti­liz­zan­do il Web Services De­scrip­tion Language WSDL. Da un punto di vista puramente tecnico, è possibile uti­liz­za­re il lin­guag­gio WSDL 2.0 per la de­scri­zio­ne delle API REST. Tuttavia, gli svi­lup­pa­to­ri tendono a con­si­de­rar­lo un processo ab­ba­stan­za complesso. Il Web Ap­pli­ca­tion De­scrip­tion Language (WADL) avrebbe dovuto risolvere questo problema, ma a causa del suo formato XML, non è mai riuscito ad af­fer­mar­si come lin­guag­gio standard.

Questo spiega come Swagger sia riuscito a scalare ra­pi­da­men­te al primo posto tra le tec­no­lo­gie più diffuse per la do­cu­men­ta­zio­ne delle in­ter­fac­ce di pro­gram­ma­zio­ne delle ap­pli­ca­zio­ni, o meglio, come Swagger sia diventato la tec­no­lo­gia più popolare per le API REST co­mu­ne­men­te uti­liz­za­te. Swagger è stato svi­lup­pa­to da Reverb, ma è ora una risorsa con licenza open source che porta il marchio della Linux Foun­da­tion, uti­liz­za­bi­le tramite l’Open API Ini­tia­ti­ve. Con­te­stual­men­te, Swagger è stato ri­bat­tez­za­to OpenAPI Spe­ci­fi­ca­tion, sebbene in­for­mal­men­te sia ancora co­no­sciu­to con il nome ori­gi­na­rio Swagger.

In una pre­sen­ta­zio­ne tenuta nel corso della API Con­fe­ren­ce, Swagger è stato pre­sen­ta­to uti­liz­zan­do l’esempio di Spring Boot e ne sono stati spiegati i po­ten­zia­li utilizzi nelle tec­no­lo­gie di utilizzo quo­ti­dia­no.

A seconda dell’ap­pli­ca­zio­ne, l’elemento centrale di Swagger consiste in un file di testo in formato JSON o YAML. L’in­ter­fac­cia utente (UI), che sem­pli­fi­ca la creazione della do­cu­men­ta­zio­ne API, è basata su HTML e Ja­va­Script. In sostanza, Swagger ha un formato neutro dal punto di vista del lin­guag­gio ed è leggibile dalle macchine. Inoltre, l’in­ter­fac­cia utente può essere uti­liz­za­ta non solo per gestire la do­cu­men­ta­zio­ne, ma anche per eseguire, ad esempio, i test ad hoc di Swagger.

Il po­ten­zia­le di Swagger risiede so­prat­tut­to nella sua espan­di­bi­li­tà, resa possibile da una libreria centrale, lo Swagger Core. L’in­ter­fac­cia utente porta il nome di Swagger UI, mentre il ge­ne­ra­to­re di codice è de­no­mi­na­to Swagger Codegen, a cui si aggiunge lo Swagger Editor.

Come per molte altre offerte open source, Swagger trae il proprio vantaggio prin­ci­pa­le dal suo vasto eco­si­ste­ma su GitHub, dove gli svi­lup­pa­to­ri possono trovare ge­ne­ra­to­ri di codice per quasi tutti i linguaggi di pro­gram­ma­zio­ne. Swagger documenta ogni in­ter­fac­cia con tutte le in­for­ma­zio­ni ne­ces­sa­rie.

Il file di do­cu­men­ta­zio­ne inizia con la spe­ci­fi­ca­zio­ne relativa alla versione uti­liz­za­ta, a cui fanno seguito le in­for­ma­zio­ni generali sull’API, riportate in ordine sotto la categoria “Info”. Swagger separa anche l’host, il percorso e l’URL, spe­ci­fi­can­do­li in­di­vi­dual­men­te. Dopo aver ultimato questo passaggio, viene indicato il media-type per tutta l’API. Questa fase può essere pa­ra­go­na­ta a un complesso sistema di flashcard.

Al termine di questa ca­te­go­riz­za­zio­ne viene vi­sua­liz­za­to il contenuto: i percorsi, gli operatori e i parametri vengono preparati insieme alle cor­ri­spon­den­ti de­scri­zio­ni. I tipi di dati vengono gestiti se­pa­ra­ta­men­te. L’in­ter­fac­cia utente di Swagger consente di vi­sua­liz­za­re il tutto non solo sotto forma di testo, ma anche gra­fi­ca­men­te. Ciò si rivela par­ti­co­lar­men­te utile per l’invio di richieste di test dirette operate dal browser. Questo mix di do­cu­men­ta­zio­ne e la pos­si­bi­li­tà di generare richieste dirette di API è il segreto della po­po­la­ri­tà di Swagger.

Per lo sviluppo delle API è es­sen­zia­le una do­cu­men­ta­zio­ne adeguata e com­pren­si­bi­le. Senza quest’ultima gli svi­lup­pa­to­ri non possono uti­liz­za­re le in­ter­fac­ce. Ciò è es­sen­zia­le so­prat­tut­to per le API di pubblico dominio: senza do­cu­men­ta­zio­ne, queste sono inutili per la comunità, non possono essere di­stri­bui­te e di con­se­guen­za non ri­scuo­to­no alcun successo.

Uti­liz­za­re Swagger è at­tual­men­te il modo migliore per do­cu­men­ta­re le API REST, poiché è in grado di mappare quasi tutti i servizi web e le in­for­ma­zio­ni relative all’in­ter­fac­cia. Swagger evolve con il sistema e tutte le modifiche apportate vengono do­cu­men­ta­te au­to­ma­ti­ca­men­te. La capacità di Swagger di me­mo­riz­za­re la do­cu­men­ta­zio­ne dell’in­ter­fac­cia REST di­ret­ta­men­te sul codice è il segreto del suo buon fun­zio­na­men­to.

Il punto di partenza di ogni sviluppo API è il codice del programma (Code First) o la de­scri­zio­ne dell’in­ter­fac­cia (Design First). Seguendo l’approccio Code First, il punto di partenza è il codice del programma. Da esso, Swagger è in grado di ricavare di­ret­ta­men­te una do­cu­men­ta­zio­ne, in­di­pen­den­te dal lin­guag­gio di pro­gram­ma­zio­ne uti­liz­za­to, in­ter­pre­ta­bi­le sia dalle macchine che dagli umani.

L’approccio al­ter­na­ti­vo al Code First è rap­pre­sen­ta­to dal Design First. Come pre­ce­den­te­men­te accennato, diversi svi­lup­pa­to­ri lavorano al lato server e al lato client di un’ap­pli­ca­zio­ne. Seguendo la me­to­do­lo­gia Design First, si genera per prima cosa la de­scri­zio­ne, mentre i codici vengono sem­pli­ce­men­te generati in un secondo momento at­tra­ver­so Swagger. Esistono ge­ne­ra­to­ri per tutti i linguaggi di pro­gram­ma­zio­ne co­mu­ne­men­te uti­liz­za­ti così come modelli che possono essere adattati o ampliati.

Swagger è quindi in grado di generare un codice API coerente in maniera quasi del tutto au­to­ma­ti­ca. Se dovessero sorgere degli errori nella pro­gram­ma­zio­ne manuale, Swagger no­ti­fi­che­rà gli stessi errori di com­pi­la­zio­ne all’utente at­tra­ver­so l’at­ti­va­zio­ne con­te­stua­le di un sistema di in­te­gra­zio­ne continua.

I vantaggi che gli utenti traggono dall’utilizzo di Swagger sor­pas­sa­no di gran lunga gli svantaggi, a tal punto da poter con­si­de­ra­re Swagger un’ec­cel­len­te ap­pli­ca­zio­ne standard per la de­scri­zio­ne di in­ter­fac­ce per API RESTful. Come molte altre ap­pli­ca­zio­ni open source, Swagger beneficia di un elevato livello di di­stri­bu­zio­ne ed è quindi sup­por­ta­to da un ampio ventaglio di tool. A dettare le sorti di Swagger vi sono giganti della tec­no­lo­gia come Microsoft, IBM e Google, che so­sten­go­no la specifica OpenAPI. Esistono tuttavia delle al­ter­na­ti­ve a Swagger: il Restful API Modelling Language (RAML), ad esempio, utilizza anch’esso YAML ed è in grado di creare de­fi­ni­zio­ni ancora più complesse di quelle ge­ne­ra­bi­li con Swagger. Nel frattempo, però, il creatore di RAML (Mulesoft) si è unito alla OpenAPI Ini­tia­ti­ve.

Un piccolo svan­tag­gio nell’utilizzo di Swagger sta pro­ba­bil­men­te nella sintassi della do­cu­men­ta­zio­ne, non sempre di immediata com­pren­sio­ne e lettura. Sebbene Swagger offra già un formato re­la­ti­va­men­te ben preparato, ci vuole spesso un po’ di tempo per riuscire a orien­tar­si. API Blueprint, che utilizza una sintassi markdown, prova che il tutto può essere ancora più semplice.

Dal sito web della Swagger UI potete scaricare il file ZIP con­te­nen­te la versione completa di Swagger. Al termine del download, dovrete decidere se eseguire Swagger in locale o su un server.

At­ten­zio­ne: se intendete eseguire Swagger in locale, avrete bisogno di MAMP. Dopo aver de­com­pres­so la cartella Swagger UI Master, copiatela nella directory di MAMP o sul server. A questo punto sarà suf­fi­cien­te ri­chia­ma­re l’URL del server o il localhost del browser e Swagger si aprirà au­to­ma­ti­ca­men­te, avviando il primo processo di do­cu­men­ta­zio­ne API.

La versione web dell’editor di Swagger fornisce una versione ancora più semplice. L’editor è uti­liz­za­bi­le di­ret­ta­men­te sul browser e, oltre al classico editor di testo, mette a di­spo­si­zio­ne una vi­sua­liz­za­zio­ne grafica della do­cu­men­ta­zio­ne.

Queste poche righe di esempio sono suf­fi­cien­ti per di­mo­stra­re la grande facilità di com­pren­sio­ne della struttura di Swagger. Tutte le in­for­ma­zio­ni sono de­no­mi­na­te in modo chiaro e risultano in­ter­pre­ta­bi­li in­di­pen­den­te­men­te dal lin­guag­gio di pro­gram­ma­zio­ne.

La do­cu­men­ta­zio­ne può quindi essere esportata di­ret­ta­men­te come file YAML o con­ver­ti­ta in formato JSON, così che possa essere letta dall’in­ter­fac­cia utente di Swagger. Il contenuto vi­sua­liz­za­to mostra prima di tutto i percorsi, le in­ter­fac­ce e gli endpoint. In seguito, vengono mostrate le de­scri­zio­ni, i parametri, le risposte e i ri­spet­ti­vi si­gni­fi­ca­ti. Negli endpoint, i test ad hoc possono essere eseguiti uti­liz­zan­do l’in­ter­fac­cia utente di Swagger.

La pos­si­bi­li­tà di provare i tool gra­tui­ta­men­te è un altro grande vantaggio della tec­no­lo­gia open source. Nel caso di Swagger, ciò è possibile per l’in­ter­fac­cia utente così come per tutti gli altri tool. In questo modo riu­sci­re­te a farvi un’idea delle pos­si­bi­li­tà offerte da Swagger.