@baloise/spectral-rules

v1.4.1

Published

6 months ago

Custom Spectral API Linter ruleset for Baloise API Guidelines based on Zalando API guidelines.

Downloads

8,130

0High
0Medium
0Low

spectral-ruleset

👷🚧🛠️ in development 👷🚧🛠️

Custom Spectral API Linter ruleset for Zalando RESTful API Guidelines.

There are two flavors of the ruleset:

zalando: Sticks to the Zalando RESTful API Guidelines
baloise: Adapts some rules to the needs of baloise

Please refer to the table below for details.

The ruleset spectral:oas is disabled by default. If you like to enable these rules again use

echo "extends: [https://raw.githubusercontent.com/baloise-incubator/spectral-ruleset/main/zalando.yml, spectral:oas]" \
    > .spectral.yml

Use it

Possibility A: Reference via Github URL

# zalando flavor:
npx @stoplight/spectral-cli lint \
    --ruleset https://raw.githubusercontent.com/baloise-incubator/spectral-ruleset/main/zalando.yml \
    example/example-openapi.yml

# baloise flavor:
npx @stoplight/spectral-cli lint \
    --ruleset https://raw.githubusercontent.com/baloise-incubator/spectral-ruleset/main/baloise.yml \
    example/example-openapi.yml

Or just create a .spectral.yml extending it

echo "extends: [https://raw.githubusercontent.com/baloise-incubator/spectral-ruleset/main/baloise.yml]" \
    > .spectral.yml
npx @stoplight/spectral-cli lint example/example-openapi.yml

If you're behind a proxy you can pass it via PROXY environment variable:

PROXY=<PROXY URL> npx @stoplight/spectral lint <...>

Possibility B: Install via npm

npm i @baloise/spectral-rules

# zalando flavor:
npx @stoplight/spectral-cli lint \
    --ruleset ./node_modules/@baloise/spectral-rules/zalando.yml \
    example/example-openapi.yml

# baloise flavor:
npx @stoplight/spectral-cli lint \
    --ruleset ./node_modules/@baloise/spectral-rules/baloise.yml \
    example/example-openapi.yml

Or just create a .spectral.yml extending it

echo "extends: [./node_modules/@baloise/spectral-rules/baloise.yml]" > .spectral.yml
npx @stoplight/spectral-cli lint example/example-openapi.yml

Development

Adding a new Rule

Choose a new, unsupported rule from the table below. For example #151 MUST specify success and error responses.
Make sure tests/fixtures/base-openapi.yml satisfies the rule.
Add a test tests/151-MUST-specify-success-and-error-responses.test.ts that
1. Takes the base-openapi.yaml as input
2. Modifies it to break the new rule
3. Expect that spectral finds the error (this will fail for now)
Extend zalando.yml with the new rule, so that the previously added test succeeds. See https://meta.stoplight.io/docs/spectral/docs/guides/4-custom-rulesets.md on how to define custom rules.
Add a :heavy_check_mark: to the table below.
Create a PR

Alternative baloise rules are marked by appending the rule number with an a. For example zalando rule #115 versus baloise rule #115a. The zalando rule #115 is defined in zalando.yml. The baloise rule #115a is defined in baloise.yml while deactivating the original zalando rule #115a.

Setup

npm install
npm run test
npm run lint
npm run lint-fix # format source files

Currently supported rules from the zalando restful-api-guidelines

:heavy_check_mark: = rule implemented
:grey_exclamation: = rule implementation not possible or to complex

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme