OpenAPI Specifications

Coveo’s standard OpenAPI ruleset is enforced using Spectral CLI. This ruleset is made available for other tools at Coveo, ensuring that API owners can lint their OpenAPI specifications.

Consuming those rules

Install from npm

From an npm project, install the rules as a standard npm package.

npm i @coveo/api-standards @stoplight/spectral-cli

Then create a local spectral.yaml file with only this configuration:

extends: "@coveo/api-standards"

Adding New Rules

To add a new rule meant to be statically enforced at Coveo, follow this process:

1. Add the rule
   Add a new rule in tools/spectral-ruleset/spectral.yaml. Follow the Spectral CLI documentation to learn how to define a new rule.

2. Add test cases

   • Add a new test case file that verifies that the new rule correctly catches an OpenAPI violation
   • Add a new entry in valid.openapi.json to verify that the new rule does not incorrectly flag a valid OpenAPI specification.

3. Test the new rule

   • Install pnpm
   • At the root of the repo, run pnpm install
   • Then run pnpm run test