From 63eb3bdc6e778da6a94d901b7f755a1227a8a996 Mon Sep 17 00:00:00 2001 From: Simone Esposito Date: Mon, 17 Jun 2024 14:35:34 +0200 Subject: [PATCH 1/2] Update readme and rulesets name. --- Makefile | 6 +- README.md | 154 ++++++++++---------------------- public/initial.yaml | 2 +- rules-modi | 2 +- src/components/RulesetSelect.js | 12 +-- src/utils.mjs | 8 +- 6 files changed, 63 insertions(+), 121 deletions(-) diff --git a/Makefile b/Makefile index c49a5993..c188e6c0 100644 --- a/Makefile +++ b/Makefile @@ -29,7 +29,7 @@ rulesets-dir: spectral.yml: ./rules-modi/rules/ rulesets-dir make -C rules-modi $@ && mv rules-modi/rulesets/$@ . - node ruleset_doc_generator.mjs --file $@ --title 'Italian API Guidelines' + node ruleset_doc_generator.mjs --file $@ --title 'Italian Guidelines Extended' spectral-generic.yml: ./rules-modi/rules/ spectral.yml rulesets-dir make -C rules-modi $@ && mv rules-modi/rulesets/$@ . node ruleset_doc_generator.mjs --file $@ --title 'Best Practices Only' @@ -38,10 +38,10 @@ spectral-security.yml: ./rules-modi/rules/ ./rules-modi/security/ rulesets-dir node ruleset_doc_generator.mjs --file $@ --title 'Extra Security Checks' spectral-full.yml: spectral.yml spectral-security.yml rulesets-dir make -C rules-modi $@ && mv rules-modi/rulesets/$@ . - node ruleset_doc_generator.mjs --file $@ --title 'Italian API Guidelines + Extra Security Checks' + node ruleset_doc_generator.mjs --file $@ --title 'Italian Guidelines Extended + Extra Security Checks' spectral-modi.yml: rulesets-dir make -C rules-modi $@ && mv rules-modi/rulesets/$@ . - node ruleset_doc_generator.mjs --file $@ --title 'ModI Guidelines' + node ruleset_doc_generator.mjs --file $@ --title 'Italian Guidelines' # Build js bundle build: install rules diff --git a/README.md b/README.md index a51f6107..21b1a0e9 100644 --- a/README.md +++ b/README.md @@ -4,116 +4,88 @@ [![API on forum.italia.it](https://img.shields.io/badge/Forum-interoperabilit%C3%A0-blue.svg)](https://forum.italia.it/c/piano-triennale/interoperabilita) [![README in English](https://img.shields.io/badge/Readme-English-darkgreen.svg)](README.en.md) -Questo repository contiene un validatore in-browser che verifica alcune delle regole per le API REST indicate nel Modello di Interoperabilità. +💡 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](https://github.com/teamdigitale/api-starter-kit). -E' in beta una [github-action che utilizza queste regole](https://github.com/teamdigitale/api-oas-checker-action). +🗂️ I progetti associati sono indicati nell'[API Starter Kit](https://github.com/teamdigitale/api-starter-kit). -L'applicazione on-line pronta all'uso è disponibile [qui](https://italia.github.io/api-oas-checker/). +👨🏻‍💻 L'applicazione on-line pronta all'uso è disponibile [qui](https://italia.github.io/api-oas-checker/). -Il validatore è basato su [Spectral](https://github.com/stoplightio/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](security/functions/) non è necessario quindi eseguire codice javascript. -Inoltre gli utenti possono sempre limitarsi ad importare le sole regole statiche. +⚙️ Il validatore è basato su [Spectral](https://github.com/stoplightio/spectral). -Le alternative valutate, ugualmente valide, sono: +> ### 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](rules-modi/security/functions/) 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](https://github.com/zalando/zally) ha bisogno di un database e non è possibile farne un webpackage; +> - [Speccy](https://github.com/wework/speccy) pare supportare solo regole in JavaScript, mentre questo validatore utilizza per lo più dei file YAML statici. -- [Zally](https://github.com/zalando/zally) ha bisogno di un database e non è possibile farne un webpackage; -- [Speccy](https://github.com/wework/speccy) pare supportare solo regole in javascript, mentre questo validatore utilizza per lo più dei file YAML statici. +## 📦 Contenuto -## Contenuto +- Una web app sviluppata con React che usa Webpack + Babel per creare una single-page application +- Due directory [rules-modi/rules](rules-modi/rules) e [rules-modi/security/](rules-modi/security/), che puntano a un altro repository, contenenti le regole applicate, che vengono poi aggregate nei seguenti file: + - [spectral-modi.yml](https://github.com/italia/api-oas-checker-rules/releases/latest/download/spectral-modi.yml), o _Italian Guidelines_ + - [spectral.yml](https://github.com/italia/api-oas-checker-rules/releases/latest/download/spectral.yml), o _Italian Guidelines Extended_ + - [spectral-generic.yml](https://github.com/italia/api-oas-checker-rules/releases/latest/download/spectral-generic.yml), o _Best Practices Only_ + - [spectral-security.yml](https://github.com/italia/api-oas-checker-rules/releases/latest/download/spectral-security.yml), o _Extra Security Checks_ + - [spectral-full.yml](https://github.com/italia/api-oas-checker-rules/releases/latest/download/spectral-full.yml), o _Italian Guidelines Extended + Extra Security Checks_ -- Una applicazione web sviluppata con React che usa Webpack + Babel per creare una single-page application -- Una directory [rules/](rules/) con le regole applicate, che vengono poi aggregate nel file [spectral.yml](https://italia.github.io/api-oas-checker/spectral.yml) -- Una directory [security/](security/) con delle ulteriori regole di sicurezza, che vengono poi aggregate nel file [spectral-security.yml](https://italia.github.io/api-oas-checker/spectral-security.yml) +La gestione delle regole è esterna: la cartella `rules-modi` punta, infatti, al repo [api-oas-checker-rules](https://github.com/italia/api-oas-checker-rules). -## Sviluppo +## 🔍 Validare le API -## Modalità online +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. -Il modo più semplice di controllare un'API è quello di eseguire i controlli usando -direttamente - o dopo averli scaricati - i file con le regole presenti su github. +In alternativa, è possibile validare le API tramite IDE, CLI e GitHub Action: si rimanda al seguente [README](https://github.com/italia/api-oas-checker-rules/blob/main/README.md) del repo [api-oas-checker-rules](https://github.com/italia/api-oas-checker-rules) per tutte le informazioni. -```bash -$ spectral lint -r https://italia.github.io/api-oas-checker/spectral.yml $OAS_URL_OR_FILE -``` +## 🚀 Avviare la web app in locale -## Modalità CI (versioned rulesets) +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. -Quando integrate il validatore in una CI, potreste voler usare una versione -specifica delle regole, anziché l'ultima. In questo caso potete fare riferimento -ai tag con prefisso `rules/X.Y.Z` (es. `rules/0.3.3`). +Per avviare l'applicazione: ```bash -$ spectral lint -r https://raw.githubusercontent.com/italia/api-oas-checker/rules/0.3.3/spectral.yml $OAS_URL_OR_FILE +$ yarn +$ yarn start ``` -## Modalità IDE - -Alcuni IDE supportano Spectral tramite delle estensioni. -Di seguito i passaggi per utilizzare il profilo di validazione completo -con [l'estensione ufficiale di Spectral per Visual Studio Code](https://github.com/stoplightio/vscode-spectral): +In alternativa: ```bash -# Installa l'estensione dal marketplace di vscode -$ code --install-extension stoplight.spectral - -# Scarica il profilo spectral-full.yml nella home del progetto -$ curl https://italia.github.io/api-oas-checker/spectral-full.yml > .spectral.yml - -# Esegui l'IDE -$ code +$ docker-compose up --build start ``` -Quando si scarica la versione online delle regole, è importante verificare periodicamente -che sia aggiornata. +e al termine della compilazione collegarsi a http://localhost:3000 -### Modalità linea di comando -Se volete controllare la vostra API ci sono due modalità: +## 📝 Come scrivere le regole -#### 1) Usando la CLI di Spectral +Spectral itera le specifiche OAS usando le espressioni JSONPath indicate nelle regole di default presenti nelle directory [rules-modi/rules](rules-modi/rules) e [rules-modi/security/](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. -dopo aver clonato il repository, eseguite: +Questo comando testa le regole presenti nel file `problem.yml` contenuto nella directory `rules-modi/rules`: ```bash -$ yarn -$ make rules -$ yarn run spectral lint -r spectral.yml $OAS_URL_OR_FILE +./test-ruleset.sh rules-modi/rules problem ``` -#### 2) Usando l'immagine docker di Spectral +Quando si modifica una regola, è necessario ricreare e validare il contenuto della snapshot con: ```bash -$ docker run --rm --entrypoint=sh \ - -v $(pwd)/api:/locale stoplight/spectral:5.9.1 \ - -c "spectral lint -r https://italia.github.io/api-oas-checker/spectral.yml /locale/openapi.yaml" +./test-ruleset.sh rules-modi/rules --snapshot problem ``` -### Modalità ui +Per ulteriori informazioni sulle regole di Spectral si veda [la documentazione ufficiale](https://stoplight.io/p/docs/gh/stoplightio/spectral/docs/getting-started/rulesets.md). -Questa applicazione web è basata sulla libreria React e usa Webpack per generare il bundle dell'applicazione con il supporto di Babel per transpilare il codice JavaScript. +### JSONPath -Per avviare l'applicazione +Sul sito [jsonpath.com](https://jsonpath.com/) si possono testare le regole online. -```bash -$ yarn -$ yarn start -``` +JSONPath supporta le back-references; si veda [questo commento](https://github.com/json-path/JsonPath/issues/287#issuecomment-265479196) per maggiori dettagli. -In alternativa - -```bash -$ docker-compose up --build start -``` +## 🪖 Testing -e al termine della compilazione collegarsi a http://127.0.0.1:3000/ - -## Testing - -E' possibile testare sia la corretta generazione delle regole spectral che la ui +Per testare le regole generate nel repo [api-oas-checker-rules](https://github.com/italia/api-oas-checker-rules) e la UI, è possibile usare i seguenti comandi: ```bash # N.B. make test non funziona correttamente su MacOS @@ -121,47 +93,15 @@ $ make test $ make test-ui ``` -In alternativa +In alternativa: ```bash $ docker-compose up --build test ``` -## Scrivere regole - -Spectral itera le specifiche OAS usando le espressioni jsonpath -indicate nelle regole di default presenti nella directory [rules](rules/) -o in quelle di sicurezza presenti nella directory [security](security/) -ed esegue le callback indicate sulle righe corrispondenti. -E' possibile testare ogni singola regola (eg. `problem` ) 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`. - -```bash -./test-ruleset.sh rules problem -``` - -Quando si modifica una regola quindi, è necessario ricreare e validare il contenuto della snapshot -con - -```bash -./test-ruleset.sh rules --snapshot problem -git add -p rules/problem* rules/tests/problem* -``` - -Vedete qui [spectral.yml](https://italia.github.io/api-oas-checker/spectral.yml) per degli esempi di regole. - -Sul sito https://jsonpath.com/ si possono testare le regole online. - -Jsonpath supporta le back-references, - si veda https://github.com/json-path/JsonPath/issues/287#issuecomment-265479196 - -Per ulteriori informazioni sulle regole di spectral si veda https://stoplight.io/p/docs/gh/stoplightio/spectral/docs/getting-started/rulesets.md - -## Contributi +## ✍🏻 Contributi Grazie a Paolo Falomo, Francesco Marinucci, Giuseppe De Marco -e Vincenzo Chianese per i suggerimenti ed i contributi! +e Vincenzo Chianese per i suggerimenti ed i contributi! \ No newline at end of file diff --git a/public/initial.yaml b/public/initial.yaml index 897fb4ab..e1998698 100644 --- a/public/initial.yaml +++ b/public/initial.yaml @@ -1,6 +1,6 @@ # This application lints your OpenAPI specification using the opensource tool Spectral. # You can use different verification profiles, including -# the one based on the Italian API Guidelines (default) +# the one based on the Italian Guidelines (default) # the one with some basic Security checks. # Paste here your OAS spec and click on "Validate" diff --git a/rules-modi b/rules-modi index b21f74e6..f4d1f15e 160000 --- a/rules-modi +++ b/rules-modi @@ -1 +1 @@ -Subproject commit b21f74e6a6f5c300e24b268371978d81c08f9f65 +Subproject commit f4d1f15e181d8908d68b873769da20c78b883a3c diff --git a/src/components/RulesetSelect.js b/src/components/RulesetSelect.js index fe4fe5e2..9465b37c 100644 --- a/src/components/RulesetSelect.js +++ b/src/components/RulesetSelect.js @@ -8,8 +8,8 @@ import { getDocFilename, RULESET_BEST_PRACTICES, RULESET_ITALIAN, - RULESET_ITALIAN_PLUS_SECURITY, - RULESET_MODI, + RULESET_ITALIAN_EXTENDED_PLUS_SECURITY, + RULESET_ITALIAN_EXTENDED, RULESET_SECURITY, } from '../utils.mjs'; @@ -48,11 +48,13 @@ export const RulesetSelect = () => { value={ruleset} onChange={(e) => dispatch(setRuleset(e.target.value))} > - - + + - + Ruleset diff --git a/src/utils.mjs b/src/utils.mjs index 26a30be5..750ce2a9 100644 --- a/src/utils.mjs +++ b/src/utils.mjs @@ -19,12 +19,12 @@ export const HINT = 'hint'; export const DEFAULT_DOCUMENT_URL = 'initial.yaml'; export const TEMPLATE_DOCUMENT_URL = 'https://raw.githubusercontent.com/teamdigitale/api-starter-kit/master/openapi/simple.yaml.src'; -export const RULESET_MODI = 'spectral-modi.yml'; -export const RULESET_ITALIAN = 'spectral.yml'; +export const RULESET_ITALIAN = 'spectral-modi.yml'; +export const RULESET_ITALIAN_EXTENDED = 'spectral.yml'; export const RULESET_BEST_PRACTICES = 'spectral-generic.yml'; export const RULESET_SECURITY = 'spectral-security.yml'; -export const RULESET_ITALIAN_PLUS_SECURITY = 'spectral-full.yml'; -export const DEFAULT_RULESET = RULESET_MODI; +export const RULESET_ITALIAN_EXTENDED_PLUS_SECURITY = 'spectral-full.yml'; +export const DEFAULT_RULESET = RULESET_ITALIAN; export const downloadFile = (content, fileName, contentType) => { const anchorElement = document.createElement('a'); From 167695ba28e423b1d18e25a5a7a53d2645ff2269 Mon Sep 17 00:00:00 2001 From: Simone Date: Mon, 17 Jun 2024 14:41:11 +0200 Subject: [PATCH 2/2] Update non-breaking.yml --- .github/workflows/non-breaking.yml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.github/workflows/non-breaking.yml b/.github/workflows/non-breaking.yml index 7db16c90..c753014d 100644 --- a/.github/workflows/non-breaking.yml +++ b/.github/workflows/non-breaking.yml @@ -13,6 +13,8 @@ jobs: steps: - uses: actions/checkout@v2 + with: + submodules: true - uses: actions/setup-node@v2 with: node-version: '16'