Skip to content

Commit

Permalink
Readme clarifications (#661)
Browse files Browse the repository at this point in the history
* README.md clarifications
  • Loading branch information
ioggstream authored Nov 17, 2022
1 parent 5d061af commit 95ef796
Show file tree
Hide file tree
Showing 2 changed files with 19 additions and 4 deletions.
12 changes: 10 additions & 2 deletions README.en.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,10 +10,18 @@ There's a Beta [github-action that uses these rules](https://github.com/teamdigi

The ready-to-use online application is available [here](https://teamdigitale.github.io/api-oas-checker).

The validator is based on [Spectral](https://github.com/stoplightio/spectral) which we preferred over other good validators:
The validator is based on [Spectral](https://github.com/stoplightio/spectral).

We preferred it because
it does not require databases or server components to process your OpenAPI documents (OAS Checker is a github pages static application),
and because the vast majority of ruleset can be described via static files (e.g. YAML):
[except for very specific cases](security/functions/) you don't need to execute javascript code.
Moreover, uses that do not trust sourcing javascript code, can just limit themself to static rules.

Other good validators we evaluated are:

- [Zally](https://github.com/zalando/zally) requires a database and cannot be webpackaged in a browser application;
- [Speccy](https://github.com/wework/speccy) seem to support only javascript rules, while our rules are described using static yaml files.
- [Speccy](https://github.com/wework/speccy) seem to support only javascript rules, while our rules are usually described using static YAML files.

## Content

Expand Down
11 changes: 9 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,10 +11,17 @@ E' in beta una [github-action che utilizza queste regole](https://github.com/tea

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) che abbiamo preferito rispetto ad altri software:
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.

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 dei file yaml statici.
- [Speccy](https://github.com/wework/speccy) pare supportare solo regole in javascript, mentre questo validatore utilizza per lo più dei file YAML statici.

## Contenuto

Expand Down

1 comment on commit 95ef796

@vercel
Copy link

@vercel vercel bot commented on 95ef796 Nov 17, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please sign in to comment.