Introduzione

In questo breve articolo vedremo OpenAPI Generator e come possiamo utilizzarlo per diminuire drasticamente i tempi di sviluppo per la fase di integrazione fra backend e frontend.

OpenAPI

OpenAPI è uno standard definito dalla OpenAPI Initiative con l'obiettivo di stabilire uno standard universale nella creazione e definizione di API Rest. Questo standard fu inizialmente creato usando le specifiche di Swagger come base. Al momento di scrittura di questo articolo ci troviamo alla versione 3.1 dello standard.

Il generatore

OpenAPI Generator è un progetto open source che si può trovare alla propria pagina GitHub.

Questo software, come anche gli altri facenti parte della collezione di OpenAPI Tools, sono mantenuti in maniera autonoma dalla community e non sono legati direttamente alla OpenAPI Initiative sopra menzionata.

Questo software permette di partire da una specifica che segue gli standard OpenAPI e generare da essa in maniera automatica del codice di integrazione come anche la documentazione e una generazione di un mock server. Per una lista completa dei linguaggi/framework supportati dal generatore vi invito a consultare direttamente la tabella presenta nella repository del progetto.

Utilizzo del generatore nell'integrazione di codice API in un progetto frontend

In questa breve guida vedremo insieme un esempio pratico di come generare del codice d'integrazione per un progetto Dart partendo dalle specifiche della live demo di Swagger UI.

Prima di tutto ci servirà avere il file JSON che definisce le API, fortunatamente Swagger ci permette di recuperare questo file molto facilmente essendoci un link di riferimento allo stesso direttamente nella nostra pagina web:

Ora che abbiamo il nostro JSON di specifica possiamo generare facilmente il codice Dart, per fare questo dobbiamo scegliere quale modalità di utilizzo del generatore è quella più comoda per il nostro caso d'uso, per questo esempio utilizzeremo il file JAR scaricato dalla pagina GitHub del progetto. Sempre dalla stessa repository è possibile trovare le altre modalità d'uso possibili del generatore.

Per semplicità in questa breve introduzione terremo il JSON delle specifiche ed il file JAR per la generazione nella stessa cartella:

ora non ci resta che navigare con il nostro terminale alla cartella in cui abbiamo posizionato i file e lanciare il seguente comando:

java -jar openapi-generator-cli.jar generate -i pet_store_swagger.json -g dart-dio -o .

Prima di vedere il risultato analizziamo brevemente la struttura del comando:

la prima parte java -jar openapi-generator-cli.jar ci indica di usare la nostra installazione locale di Java per eseguire il file JAR che passiamo come primo parametro.

Successivamente possiamo vedere che passiamo alla parte vera e propria del generatore usando il comando generate, a questo passiamo un parametro -i che indica il file sorgente per la definizione delle API a cui come passiamo come parametro pet_store_swagger.json ovvero il file JSON che abbiamo scaricato in precedenza.

Il secondo argomento per il nostro comando di generazione è -g il quale serve ad indicare il formato dell'output che desideriamo avere, nel nostro caso questo sarà dart-dio (ci sono alcune differenze fra questo ed il generatore normale di dart, ma al fine di questa introduzione non è davvero rilevante). Una lista completa dei generatori possibili è consultabile qui.

Infine come ultimo parametro abbiamo -o che specifica dove desideriamo che venga generato il risultato della generazione, nel nostro esempio il codice verrà generato nella stessa cartella in cui risiedono il file JAR ed il JSON quindi useremo il valore . .

Possiamo vedere ora che nella cartella ci sono molti più file come risultato della generazione avvenuta con successo:

Oltre al codice vero che troveremo all'interno della cartella "lib" possiamo anche vedere come il generatore ha generato anche una parte di documentazione. Quest'ultima consultabile nel file README.md per quanto riguarda una descrizione ad alto livello quanto risiede nel file JSON come anche nei singoli file all'interno della cartella "doc" dove troveremo le descrizioni dei modelli delle varie componenti.

Per quanto riguarda la parte di codice generato avremmo una struttura come la seguente:

Il codice sarà già suddiviso in parti di utilizzo del singoli endpoint che possiamo trovare all'interno della cartella "api", il codice legato all'autenticazione dentro la cartella "auth" ed i modelli utilizzati all'interno della cartella model. Nella root della directory "src" troveremo invece il codice che gestisce la parte delle chiamate HTTP.

Oltre a queste due parti vi è quella di generazione dei file di test che fungono da base di partenza per poter scrivere i propri test d'integrazione.

Conclusione

La generazione di codice tramite l'utilizzo del generatore di OpenAPI Tools permette di ridurre notevolmente i tempi di sviluppi nella parte di integrazione fra backend e frontend qualora questi fossero 2 applicativi completamente separati e può permettere a due team differenti di lavoro di comunicare più facilmente in quanto solo un file JSON è necessario per permettere la creazione di questo codice, senza una reale necessità di conoscere a perfezione il codice backend o come siano strutturati gli endpoint.