💡 Questo repository contiene un checker 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.

• Node.js 16+ (vedi .nvmrc)
• Yarn (consigliato) o npm
• Docker (opzionale, per eseguire in container)

Il modo più semplice per controllare un'API è di utilizzare questo checker, inserendo il contenuto dell'API e selezionando un set di regole (di default: Italian Guidelines Full). Cliccando su "Check" sarà possibile esaminare tutti gli errori, warning, info e hint rilevati da Spectral.

📌 Per la pubblicazione di una API sul Catalogo PDND, eseguire l'OAS Checker con il profilo Italian Guidelines Full e verificare che lo yaml presenti 0 errori ed auspicabilmente 0 warnings.

In alternativa, è possibile fare il check delle API tramite IDE, CLI e GitHub Action: si rimanda al seguente README del repo api-oas-checker-rules per tutte le informazioni.

Le regole che il checker utilizza sono gestite in un repository dedicato: api-oas-checker-rules.

I ruleset disponibili sono scaricabili dalle release del repository:

• spectral.yml, o Italian Guidelines Full, quelle di default
• spectral-generic.yml, o Best Practices Only
• spectral-security.yml, o Extra Security Checks
• spectral-full.yml, o Italian Guidelines Full + Extra Security Checks

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://localhost:3000

Per eseguire i test:

$ yarn test

• Modello di Interoperabilità: Linee guida ufficiali
• Regole complete: Repository api-oas-checker-rules
• GitHub Action: Esempio di configurazione per CI/CD
• API Starter Kit: Progetti correlati

Grazie a Paolo Falomo, Francesco Marinucci, Giuseppe De Marco, Andrea Misuraca, Simone Esposito, Rocco Affinito e Vincenzo Chianese per i suggerimenti ed i contributi!

⚙️ Il checker è basato su Spectral.

Perché 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 (es. set di regole per la security), non è necessario quindi eseguire codice JavaScript. Inoltre, gli utenti possono sempre limitarsi ad importare le sole regole statiche.

Le alternative valutate, ugualmente valide, sono:

• Zally ha bisogno di un database e non è possibile farne un webpackage;
• Speccy pare supportare solo regole in JavaScript, mentre questo checker utilizza per lo più dei file YAML statici.