Ormai dietro quasi ogni interfaccia mobile o web lavorano API REST che si occupano dell’approvvigionamento di dati da e verso server remoti. I backend REST possono essere realizzati in svariate tecnologie, ma una volta portati a termine è necessario documentarli con precisione affinché risultino realmente utilizzabili. Swagger è un progetto open source molto interessante, totalmente dedicato alla documentazione delle API REST.

Per ogni possibile invocazione ad un servizio REST, è necessario conoscere un certo insieme di aspetti:

• l’URL da contattare comprensivo di porta TCP;
• il metodo HTTP per l’invocazione (GET, POST, PUT o DELETE);
• descrizione di ogni azione che può essere svolta;
• parametri in input includendo loro numero, tipologia e modalità di inoltro (nella query string, incorporati nel path o nel body della richiesta);
• risultati da attendersi in funzione dell’esito dell’operazione sia come codice di stato HTTP sia come parametri restituiti.

Swagger dispone di un editor che può essere provato in un’apposita demo.

Sul lato sinistro, si scrive il codice sorgente della documentazione sfruttando un formato molto flessibile, YAML (anche se Swagger lavora bene anche con JSON), mentre sulla destra è collocato il riquadro dell’anteprima che mostra come apparirà il risultato finale. Notare, proprio nella figura, come i parametri definiti nel codice YAML vengano tradotti nell’interfaccia utente: ad esempio, il parametro info/title (valorizzato come “Simple API”) diventa il titolo della pagina. YAML nasce come formato di serializzazione più immediato rispetto a XML e, come si può già vedere, basa la struttura gerarchica di elementi su indentazione ed altri semplici elementi come il simbolo ‘-‘ per rappresentare le voci di un elenco. L’editor Swagger comunque non ci lascerà soli durante la compilazione suggerendoci costantemente le parole chiave da utilizzare.

A lavoro completato, la documentazione verrà visualizzata sotto forma di pagine web e Swagger riduce al minimo le difficoltà permettendo di scaricarle già dotate di server scegliendo tra le varie tecnologie disponibili:

Si può vedere un esempio di documentazione Swagger consultando una demo della Swagger UI. Navigando tra le specifiche proposte per ogni metodo si può notare la presenza del comando “Try it out!” che permetterà di inserire direttamente i parametri richiesti e consultarne i risultati completi (codice di stato, body della risposta, header HTTP).

Swagger è un progetto vasto, composto da molti strumenti. Qui ne abbiamo introdotto gli aspetti fondamentali tanto per iniziare ad utilizzarlo e, soprattutto, per renderci conto che per la documentazione delle nostre API REST non c’è nulla da inventare: come abbiamo appena visto, esiste uno strumento intelligente, innovativo e perfettamente confacente al compito.

Commentate e fateci sapere cosa ne pensate!