Skip to content

Latest commit

 

History

History
163 lines (111 loc) · 5.5 KB

README.en.md

File metadata and controls

163 lines (111 loc) · 5.5 KB
Raw

APIs checker compliant to the Italian Interoperability Framework

Join the #api channel API on forum.italia.it

This repository contains an in-browser checker that verifies some of the rules for the REST APIs, as indicated in the Interoperability Model.

The associated projects are indicated in the API Starter Kit. There's a Beta github-action that uses these rules.

The ready-to-use online application is available here.

The checker is based on 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 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 checkers we evaluated are:

  • Zally requires a database and cannot be webpackaged in a browser application;
  • Speccy seem to support only javascript rules, while our rules are usually described using static YAML files.

Content

  • A web application developed with React using Webpack + Babel to create a single-page application
  • A directory rules/ with the applied rules, which are then aggregated in the file spectral.yml
  • A directory security/ with additional security rules, which are then aggregated into the file spectral-security.yml

Development

Online mode

The simplest way to check an API is to run the checks using directly - or after downloading them - the rule files on github.

$ spectral lint -r https://italia.github.io/api-oas-checker/spectral.yml $OAS_URL_OR_FILE

CI Mode (versioned rulesets)

When embedding the checker in a CI, you may want to use a specific version of the rules instead of the latest one. version of the rules instead of the latest one. In this case, you can refer to tags prefixed with rules/X.Y.Z (e.g. rules/0.3.3).

$ spectral lint -r https://raw.githubusercontent.com/italia/api-oas-checker/rules/0.3.3/spectral.yml $OAS_URL_OR_FILE

IDE mode

Some IDEs support Spectral via extensions. Here are the steps to use the complete checking profile with the official Spectral extension for Visual Studio Code:

# Install the extension from the vscode marketplace
$ code --install-extension stoplight.spectral

# Download the profile spectral-full.yml to your project home
$ curl https://italia.github.io/api-oas-checker/spectral-full.yml > .spectral.yml

# Run the IDE
$ code

When downloading the online version of the rules, it is important to periodically check that it is up-to-date.

Command line mode

If you want to control your API there are two ways:

1) Using the Spectral CLI

If you want to control your API using the CLI of Spectral, after cloning the repo, just launch

$ yarn
$ make rules
$ yarn run spectral lint -r spectral.yml $OAS_URL_OR_FILE

2) Using Spectral docker image

$ 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"

UI mode

This web application is based on React library and uses Webpack as a bundler and Babel to transpile JavaScript code

To launch the application

$ yarn
$ yarn start

or alternatively

$ docker-compose up --build start

and then when the build is finished, connect to http://127.0.0.1:3000/

Testing

It is possible to test boht the correct spectral rules generation and the ui

# N.B. make test doens't work correctly on MacOS
$ make test
$ make test-ui

or alternatively

$ docker-compose up --build test

Write rules

Spectral iterates the OAS specifications using jsonpath expressions indicated in the rules and executes the callbacks indicated on the corresponding lines. It is possible to test every single rule (e.g. problem) by verifying that the spectral output corresponds to that indicated in the associated .snapshot file

./test-ruleset.sh rules problem

Therefore, when editing a rule, it is necessary to recreate and check the contents of the snapshot with

./test-ruleset.sh rules --snapshot problem
git add -p rules/problem*

See here spectral.yml for examples of rules.

You can test the rules online here: http://jsonpath.com/ .

Jsonpath supports back-references, see json-path/JsonPath#287 (comment)

For more information on spectral rules see https://stoplight.io/p/docs/gh/stoplightio/spectral/docs/getting-started/rulesets.md

Acknowledgements

Thanks to the following contributors for their code and ideas: Paolo Falomo, Giuseppe De Marco, Francesco Marinucci and Vincenzo Chianese.