https://github.com/italia/api-oas-checker
An OpenAPI 3 checker based on spectral.
https://github.com/italia/api-oas-checker
api d3f-staticanalysistool hacktoberfest linter openapi3 openapi3-validation quality rest sast security
Last synced: 9 days ago
JSON representation
An OpenAPI 3 checker based on spectral.
- Host: GitHub
- URL: https://github.com/italia/api-oas-checker
- Owner: italia
- License: other
- Created: 2020-03-02T11:23:30.000Z (about 6 years ago)
- Default Branch: master
- Last Pushed: 2026-02-16T16:57:53.000Z (about 2 months ago)
- Last Synced: 2026-02-17T00:16:40.669Z (about 2 months ago)
- Topics: api, d3f-staticanalysistool, hacktoberfest, linter, openapi3, openapi3-validation, quality, rest, sast, security
- Language: JavaScript
- Homepage: https://italia.github.io/api-oas-checker/
- Size: 26.9 MB
- Stars: 68
- Watchers: 7
- Forks: 28
- Open Issues: 38
-
Metadata Files:
- Readme: README.en.md
- License: LICENSE
- Publiccode: publiccode.yml
Awesome Lists containing this project
README
# APIs Checker Compliant to the Italian Interoperability Framework
[](https://developersitalia.slack.com/messages/CDKBYTG74)
[](https://forum.italia.it/c/piano-triennale/interoperabilita)
[](README.md)
💡 This repository contains an in-browser checker that verifies some of the rules for REST APIs as indicated in the Italian Interoperability Framework.
🗂️ The associated projects are indicated in the [API Starter Kit](https://github.com/teamdigitale/api-starter-kit).
👨🏻💻 The ready-to-use online application is available [here](https://italia.github.io/api-oas-checker/).
## 📋 Requirements
- Node.js 16+ (see `.nvmrc`)
- Yarn (recommended) or npm
- Docker (optional, for running in containers)
## 🔍 Checking APIs
The simplest way to check an API is to use this checker by entering the API content and selecting a ruleset (default: _Italian Guidelines Full_). By clicking "Check", you can examine all errors, warnings, info, and hints detected by Spectral.
📌 **For publishing an API on the PDND Catalogue**, run the OAS Checker with the **_Italian Guidelines Full_** profile and verify that the _yaml_ has **0 errors** and ideally **0 warnings**.
Alternatively, you can check APIs via IDE, CLI, and GitHub Action: please refer to the following [README](https://github.com/italia/api-oas-checker-rules/blob/main/README.md) of the [api-oas-checker-rules](https://github.com/italia/api-oas-checker-rules) repository for all the information.
## 📦 Rules
The rules used by the checker are managed in a dedicated repository: [api-oas-checker-rules](https://github.com/italia/api-oas-checker-rules).
The available rulesets can be downloaded from the [repository releases](https://github.com/italia/api-oas-checker-rules/releases/latest):
- [spectral.yml](https://github.com/italia/api-oas-checker-rules/releases/latest/download/spectral.yml), or _Italian Guidelines Full_, the default ones
- [spectral-generic.yml](https://github.com/italia/api-oas-checker-rules/releases/latest/download/spectral-generic.yml), or _Best Practices Only_
- [spectral-security.yml](https://github.com/italia/api-oas-checker-rules/releases/latest/download/spectral-security.yml), or _Extra Security Checks_
- [spectral-full.yml](https://github.com/italia/api-oas-checker-rules/releases/latest/download/spectral-full.yml), or _Italian Guidelines Full + Extra Security Checks_
## 🚀 Running the Web App Locally
This web app is based on the React library and uses Webpack to generate the application bundle with Babel support for transpiling JavaScript code.
To start the application:
```bash
$ yarn
$ yarn start
```
Alternatively:
```bash
$ docker-compose up --build start
```
and when the build is finished, connect to http://localhost:3000
## 🧪 Tests
To run the tests:
```bash
$ yarn test
```
## 📚 Documentation and Integrations
- **Interoperability Framework**: [Official guidelines](https://docs.italia.it/italia/piano-triennale-ict/lg-modellointeroperabilita-docs)
- **Complete rules**: [api-oas-checker-rules repository](https://github.com/italia/api-oas-checker-rules)
- **GitHub Action**: [CI/CD configuration example](https://github.com/italia/api-oas-checker-rules/blob/main/docs/resources/github-action.yml)
- **API Starter Kit**: [Related projects](https://github.com/teamdigitale/api-starter-kit)
## ✍🏻 Contributions
Thanks to Paolo Falomo,
Francesco Marinucci,
Giuseppe De Marco,
Andrea Misuraca,
Simone Esposito,
Rocco Affinito
and Vincenzo Chianese for their suggestions and contributions!
⚙️ The checker is based on [Spectral](https://github.com/stoplightio/spectral).
> ### Why Spectral? 🤔
> We preferred it over other software because
it doesn't require the use of databases or server components to which you would send your OpenAPI documents (OAS Checker is a static page deployed on GitHub Pages) and because most rules are described through static files (e.g. YAML):
except in specific cases (e.g. security rulesets), it's not necessary to execute JavaScript code. Furthermore, users can always limit themselves to importing only the static rules.
>
> The alternatives we evaluated, equally valid, are:
> - [Zally](https://github.com/zalando/zally) needs a database and cannot be webpackaged;
> - [Speccy](https://github.com/wework/speccy) seems to support only JavaScript rules, while this checker mostly uses static YAML files.