Merge pull request #699 from italia/update_readme

Update readme and rulesets name.
italia · Jun 17, 2024 · 4ccd9f9 · 4ccd9f9
2 parents a9f7636 + 167695b
commit 4ccd9f9
Show file tree

Hide file tree

Showing 7 changed files with 65 additions and 121 deletions.
diff --git 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'

diff --git 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
@@ -4,164 +4,104 @@
 [![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
 $ 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!
diff --git 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
diff --git 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))}
       >
-        <option value={RULESET_MODI}>ModI Guidelines</option>
-        <option value={RULESET_ITALIAN}>Italian API Guidelines</option>
+        <option value={RULESET_ITALIAN}>Italian Guidelines</option>
+        <option value={RULESET_ITALIAN_EXTENDED}>Italian Guidelines Extended</option>
         <option value={RULESET_BEST_PRACTICES}>Best Practices Only</option>
         <option value={RULESET_SECURITY}>Extra Security Checks</option>
-        <option value={RULESET_ITALIAN_PLUS_SECURITY}>Italian API Guidelines + Extra Security Checks</option>
+        <option value={RULESET_ITALIAN_EXTENDED_PLUS_SECURITY}>
+          Italian Guidelines Extended + Extra Security Checks
+        </option>
       </select>
       <a className={classes.anchor} href={getDocFilename(ruleset)} rel="noreferrer" target="_blank">
         Ruleset

diff --git 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');