Swagger: sviluppare API più comodamente

La creazione della documentazione è una delle parti che richiede più tempo nei progetti di sviluppo di applicazioni web e, spesso, chi non è coinvolto in questo processo fatica a comprenderne l’importanza per la manutenzione e l’ulteriore sviluppo dei sistemi. Il valore di questo processo, però, risulta evidente soprattutto nel momento in cui un gruppo esterno a quello di sviluppo tenta di effettuare la manutenzione e apportare migliorie all’applicazione, una pratica molto diffusa.

La documentazione delle API, cioè delle Application Programming Interfaces o interfacce di programmazione delle applicazioni, riveste un ruolo ancora più importante. Le API servono a collegare le applicazioni tra loro e a integrarle con fonti di dati e altri sistemi. La quasi totalità delle applicazioni che si utilizzano quotidianamente si serve di una moltitudine di API che svolgono un ruolo centrale nelle connessioni software. Tuttavia, per poter utilizzare queste interfacce, bisogna anche conoscerne la struttura e le funzioni. Ciò è reso possibile dalla specifica OpenAPI Swagger, il formato di descrizione aperto grazie al quale è possibile tenere traccia delle diverse funzionalità delle API. Swagger consente di standardizzare i processi di documentazione, rendendo la creazione delle API possibile anche per chi non ha preso parte al processo di sviluppo, grazie alla condivisione delle interfacce utilizzate e alla possibilità di documentarle fin da subito.

In passato, la descrizione delle API risultava molto complessa a causa delle diverse tecnologie impiegate e degli altrettanto diversi linguaggi di programmazione. Un primo importante passo verso un sistema più regolare si è compiuto quando REST è diventato il modello di programmazione per lo sviluppo delle API. Siti web come Google, Amazon e Twitter utilizzano API RESTful. Precedentemente, le interfacce di programmazione venivano descritte utilizzando il Web Services Description Language WSDL. Da un punto di vista puramente tecnico, è possibile utilizzare il linguaggio WSDL 2.0 per la descrizione delle API REST. Tuttavia, gli sviluppatori tendono a considerarlo un processo abbastanza complesso. Il Web Application Description Language (WADL) avrebbe dovuto risolvere questo problema, ma a causa del suo formato XML, non è mai riuscito ad affermarsi come linguaggio standard.

Questo spiega come Swagger sia riuscito a scalare rapidamente al primo posto tra le tecnologie più diffuse per la documentazione delle interfacce di programmazione delle applicazioni, o meglio, come Swagger sia diventato la tecnologia più popolare per le API REST comunemente utilizzate. Swagger è stato sviluppato da Reverb, ma è ora una risorsa con licenza open source che porta il marchio della Linux Foundation, utilizzabile tramite l’Open API Initiative. Contestualmente, Swagger è stato ribattezzato OpenAPI Specification, sebbene informalmente sia ancora conosciuto con il nome originario Swagger.

In una presentazione tenuta nel corso della API Conference, Swagger è stato presentato utilizzando l’esempio di Spring Boot e ne sono stati spiegati i potenziali utilizzi nelle tecnologie di utilizzo quotidiano.

A seconda dell’applicazione, l’elemento centrale di Swagger consiste in un file di testo in formato JSON o YAML. L’interfaccia utente (UI), che semplifica la creazione della documentazione API, è basata su HTML e JavaScript. In sostanza, Swagger ha un formato neutro dal punto di vista del linguaggio ed è leggibile dalle macchine. Inoltre, l’interfaccia utente può essere utilizzata non solo per gestire la documentazione, ma anche per eseguire, ad esempio, i test ad hoc di Swagger.

Il potenziale di Swagger risiede soprattutto nella sua espandibilità, resa possibile da una libreria centrale, lo Swagger Core. L’interfaccia utente porta il nome di Swagger UI, mentre il generatore di codice è denominato Swagger Codegen, a cui si aggiunge lo Swagger Editor.

Come per molte altre offerte open source, Swagger trae il proprio vantaggio principale dal suo vasto ecosistema su GitHub, dove gli sviluppatori possono trovare generatori di codice per quasi tutti i linguaggi di programmazione. Swagger documenta ogni interfaccia con tutte le informazioni necessarie.

Il file di documentazione inizia con la specificazione relativa alla versione utilizzata, a cui fanno seguito le informazioni generali sull’API, riportate in ordine sotto la categoria “Info”. Swagger separa anche l’host, il percorso e l’URL, specificandoli individualmente. Dopo aver ultimato questo passaggio, viene indicato il media-type per tutta l’API. Questa fase può essere paragonata a un complesso sistema di flashcard.

Al termine di questa categorizzazione viene visualizzato il contenuto: i percorsi, gli operatori e i parametri vengono preparati insieme alle corrispondenti descrizioni. I tipi di dati vengono gestiti separatamente. L’interfaccia utente di Swagger consente di visualizzare il tutto non solo sotto forma di testo, ma anche graficamente. Ciò si rivela particolarmente utile per l’invio di richieste di test dirette operate dal browser. Questo mix di documentazione e la possibilità di generare richieste dirette di API è il segreto della popolarità di Swagger.

Per lo sviluppo delle API è essenziale una documentazione adeguata e comprensibile. Senza quest’ultima gli sviluppatori non possono utilizzare le interfacce. Ciò è essenziale soprattutto per le API di pubblico dominio: senza documentazione, queste sono inutili per la comunità, non possono essere distribuite e di conseguenza non riscuotono alcun successo.

Utilizzare Swagger è attualmente il modo migliore per documentare le API REST, poiché è in grado di mappare quasi tutti i servizi web e le informazioni relative all’interfaccia. Swagger evolve con il sistema e tutte le modifiche apportate vengono documentate automaticamente. La capacità di Swagger di memorizzare la documentazione dell’interfaccia REST direttamente sul codice è il segreto del suo buon funzionamento.

Il punto di partenza di ogni sviluppo API è il codice del programma (Code First) o la descrizione dell’interfaccia (Design First). Seguendo l’approccio Code First, il punto di partenza è il codice del programma. Da esso, Swagger è in grado di ricavare direttamente una documentazione, indipendente dal linguaggio di programmazione utilizzato, interpretabile sia dalle macchine che dagli umani.

L’approccio alternativo al Code First è rappresentato dal Design First. Come precedentemente accennato, diversi sviluppatori lavorano al lato server e al lato client di un’applicazione. Seguendo la metodologia Design First, si genera per prima cosa la descrizione, mentre i codici vengono semplicemente generati in un secondo momento attraverso Swagger. Esistono generatori per tutti i linguaggi di programmazione comunemente utilizzati così come modelli che possono essere adattati o ampliati.

Swagger è quindi in grado di generare un codice API coerente in maniera quasi del tutto automatica. Se dovessero sorgere degli errori nella programmazione manuale, Swagger notificherà gli stessi errori di compilazione all’utente attraverso l’attivazione contestuale di un sistema di integrazione continua.

I vantaggi che gli utenti traggono dall’utilizzo di Swagger sorpassano di gran lunga gli svantaggi, a tal punto da poter considerare Swagger un’eccellente applicazione standard per la descrizione di interfacce per API RESTful. Come molte altre applicazioni open source, Swagger beneficia di un elevato livello di distribuzione ed è quindi supportato da un ampio ventaglio di tool. A dettare le sorti di Swagger vi sono giganti della tecnologia come Microsoft, IBM e Google, che sostengono la specifica OpenAPI. Esistono tuttavia delle alternative a Swagger: il Restful API Modelling Language (RAML), ad esempio, utilizza anch’esso YAML ed è in grado di creare definizioni ancora più complesse di quelle generabili con Swagger. Nel frattempo, però, il creatore di RAML (Mulesoft) si è unito alla OpenAPI Initiative.

Un piccolo svantaggio nell’utilizzo di Swagger sta probabilmente nella sintassi della documentazione, non sempre di immediata comprensione e lettura. Sebbene Swagger offra già un formato relativamente ben preparato, ci vuole spesso un po’ di tempo per riuscire a orientarsi. 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 contenente la versione completa di Swagger. Al termine del download, dovrete decidere se eseguire Swagger in locale o su un server.

Attenzione: se intendete eseguire Swagger in locale, avrete bisogno di MAMP. Dopo aver decompresso la cartella Swagger UI Master, copiatela nella directory di MAMP o sul server. A questo punto sarà sufficiente richiamare l’URL del server o il localhost del browser e Swagger si aprirà automaticamente, avviando il primo processo di documentazione API.

La versione web dell’editor di Swagger fornisce una versione ancora più semplice. L’editor è utilizzabile direttamente sul browser e, oltre al classico editor di testo, mette a disposizione una visualizzazione grafica della documentazione.

Queste poche righe di esempio sono sufficienti per dimostrare la grande facilità di comprensione della struttura di Swagger. Tutte le informazioni sono denominate in modo chiaro e risultano interpretabili indipendentemente dal linguaggio di programmazione.

La documentazione può quindi essere esportata direttamente come file YAML o convertita in formato JSON, così che possa essere letta dall’interfaccia utente di Swagger. Il contenuto visualizzato mostra prima di tutto i percorsi, le interfacce e gli endpoint. In seguito, vengono mostrate le descrizioni, i parametri, le risposte e i rispettivi significati. Negli endpoint, i test ad hoc possono essere eseguiti utilizzando l’interfaccia utente di Swagger.

La possibilità di provare i tool gratuitamente è un altro grande vantaggio della tecnologia open source. Nel caso di Swagger, ciò è possibile per l’interfaccia utente così come per tutti gli altri tool. In questo modo riuscirete a farvi un’idea delle possibilità offerte da Swagger.