💡 Questo repository contiene un validatore in-browser che verifica alcune delle regole per le API REST indicate nel Modello di Interoperabilità.
🗂️ I progetti associati sono indicati nell'API Starter Kit.
👨🏻💻 L'applicazione on-line pronta all'uso è disponibile qui.
⚙️ Il validatore è basato su Spectral.
Lo abbiamo preferito rispetto ad altri software perché non richiede l'utilizzo di database o componenti server a cui inviare i tuoi documenti OpenAPI (OAS Checker è una pagina statica deployata su GitHub Pages) e perché la maggior parte delle regole è descritta tramite file statici (e.g. YAML): tranne in casi specifici non è necessario quindi eseguire codice JavaScript. Inoltre, gli utenti possono sempre limitarsi ad importare le sole regole statiche.
Le alternative valutate, ugualmente valide, sono:
- Una web app sviluppata con React che usa Webpack + Babel per creare una single-page application
- Due directory rules-modi/rules e rules-modi/security/, che puntano a un altro repository, contenenti le regole applicate, che vengono poi aggregate nei seguenti file:
- spectral-modi.yml, o Italian Guidelines
- spectral.yml, o Italian Guidelines Extended
- spectral-generic.yml, o Best Practices Only
- spectral-security.yml, o Extra Security Checks
- spectral-full.yml, o Italian Guidelines Extended + Extra Security Checks
La gestione delle regole è esterna: la cartella rules-modi
punta, infatti, al repo api-oas-checker-rules.
Il modo più semplice per controllare un'API è di utilizzare la versione web di questo validatore, inserendo il contenuto dell'API e selezionando un set di regole. Sarà, quindi, possibile esaminare tutti gli errori, warning, info e hint rilevati da Spectral.
In alternativa, è possibile validare le API tramite IDE, CLI e GitHub Action: si rimanda al seguente README del repo api-oas-checker-rules per tutte le informazioni.
Questa web app è basata sulla libreria React e usa Webpack per generare il bundle dell'applicazione con il supporto di Babel per transpilare il codice JavaScript.
Per avviare l'applicazione:
$ yarn
$ yarn start
In alternativa:
$ docker-compose up --build start
e al termine della compilazione collegarsi a http:https://localhost:3000
Spectral itera le specifiche OAS usando le espressioni JSONPath indicate nelle regole di default presenti nelle directory rules-modi/rules e rules-modi/security/ ed esegue le callback indicate sulle righe corrispondenti. È possibile testare ogni singolo file di regole (ad esempio, problem.yml) verificando che l’output di Spectral corrisponda a quello indicato nel file .snapshot associato.
Questo comando testa le regole presenti nel file problem.yml
contenuto nella directory rules-modi/rules
:
./test-ruleset.sh rules-modi/rules problem
Quando si modifica una regola, è necessario ricreare e validare il contenuto della snapshot con:
./test-ruleset.sh rules-modi/rules --snapshot problem
Per ulteriori informazioni sulle regole di Spectral si veda la documentazione ufficiale.
Sul sito jsonpath.com si possono testare le regole online.
JSONPath supporta le back-references; si veda questo commento per maggiori dettagli.
Per testare le regole generate nel repo api-oas-checker-rules e la UI, è possibile usare i seguenti comandi:
# N.B. make test non funziona correttamente su MacOS
$ make test
$ make test-ui
In alternativa:
$ docker-compose up --build test
Grazie a Paolo Falomo, Francesco Marinucci, Giuseppe De Marco e Vincenzo Chianese per i suggerimenti ed i contributi!