@zapier/spectral-api-ruleset

@zapier/spectral-api-ruleset

Node package for linting API schemas using Spectral.

Ownership • Features • Installation • Usage • Development

---

Ownership

TBD

Features

Provides a Spectral linting ruleset to lint API schemas against Zapier's API Design Guidelines.

Installation

yarn add -D @stoplight/spectral-cli
yarn add -D @zapier/spectral-api-ruleset

For some reason, installing the CLI global and running spectral lint or npx spectral lint always fails to find the package. Adding the CLI as local dependency and then running either yarn spectral lint does work.

Usage

CLI

Create a local spectral.yaml like ours that extends the ruleset provided by the package:

extends:
  - '@zapier/spectral-api-ruleset'

Then run:

yarn spectral lint your-schema.yaml

See the Spectral CLI docs for more details.

CI

Use a Gitlab job like the following

lint:schema:
  stage: validate
  before_script:
    - mkdir spectral
  script:
    - yarn spectral lint your-schema.yaml -o spectral/junit.xml -f junit
  artifacts:
    when: always
    paths:
      - spectral
    reports:
      junit: spectral/junit.xml

See Continuous Integration docs for more details.

Development

See CONTRIBUTING, also for information on how we use @changesets/cli to version and publish.

Adding Rules

You can add rules to spectral.js. See the Alternative JS Ruleset Format docs for details.

We're using the JS format so that the package ruleset can also be used in JavaScript.

• Try to use the Core Functions to avoid custom functions.
• Include a unit test for any custom functions you add to functions/.
• Update test-schema.yaml to meet all rules (run yarn test:integrate to verify).