@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 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 src/index.ts. 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.

• Provide the correct severity (error for musts and warn for shoulds).
• Provide a clear description, as well as a documentationUrl that points to the relevant guide.
• Provide a message, which in most cases should just be {{error}}.
• Prefer Core Functions over Custom Functions.
• Include a unit test for any custom functions you add to src/functions.
• Update tests/schema.yaml to meet all rules (run yarn test:spectral to verify).
• Add failing schemas to tests/__fixtures__ and run yarn test integrations --updateSnapshot to update test/__snapshots__/integration.test.ts.snap and verify the found issues.