api-linter-rules

Schwarz API spectral custom rulesets to be used with Spectral Linter toolset. You can use this rules to integrate them in your own development workflow or you can build upon your own interpretation of how an API should look like.

Rulesets are based on file inheritance on custom rulesets as supported by Spectral Rulesets assuming that different API types use the same ruleset but different severity levels as provided by Spectral Custom Rulesets. All API type specific rulesets depend on the same base ruleset files and just overwrite rulesets or severity levels.

Example how to overwrite severity levels in spectral-api.yml:

extends:
  - https://raw.githubusercontent.com/SchwarzIT/api-linter-rules/main/spectral.yml
rules:
  operation-tag-defined: off
  common-responses-unauthorized: warn

---

Base ruleset

• Base ruleset is defined inside the asyncapi / openapi package and published as part of the latest release
• Extends from spectral:oas recommended rules
• Is generated by merging it with all individual rules at build time

Supported API Types

• Product API ruleset is defined in spectral-api.yml

  https://raw.githubusercontent.com/SchwarzIT/api-linter-rules/main/spectral-api.yml
  

• Backend For Frontend is defined in spectral-bff.yml

  https://raw.githubusercontent.com/SchwarzIT/api-linter-rules/main/spectral-bff.yml
  

• Legacy API is defined in spectral-legacy.yml

  https://raw.githubusercontent.com/SchwarzIT/api-linter-rules/main/spectral-legacy.yml
  

Local usage in IDE

Visual Studio Code

• Install Spectral Linter for VS Code
• Copy rules in your repo and create VS Code settings as described in the plugin repo OR just reference the desired API type validation from this repository like shown underneath:

1. Create "spectral.config.yml" in the root of you repository and paste below content into it

extends:
  - https://raw.githubusercontent.com/SchwarzIT/api-linter-rules/main/spectral-{API_TYPE}.yml

2. Adapt VS Code settings in .vscode/settings.json

"spectral.rulesetFile": "./spectral.config.yml",
"spectral.validateFiles": [
    "**/openapi/**/*.json",
],

3. Place your open api spec in a folder called "openapi"

4. Enjoy API Linting

Jetbrains IDE family

• Install Spectral Linter for Jetbrains IDE´s

• Open Jetbrains IDE preferences/tools/spectral and configure source rule set (see API Types above) for API linting and files to be linted

• Enjoy API linting in Jetbrains IDE family

Usage in CI

To use any of the rulesets as part of your CI please use the official Spectral CLI. E.g. to lint a file called openapi.json using the "API" ruleset run:

spectral lint -r https://raw.githubusercontent.com/SchwarzIT/api-linter-rules/main/spectral-api.yml openapi.json

Getting started

To work on this repo follow these steps:

1. Make sure you have Node.js installed with the version matching the one inside .node-version (using a tool like e.g. fnm will ensure this automatically)
2. Make sure you have pnpm installed in the version specified inside package.json (this can be automated as well using corepack)
3. Clone the repository: git clone https://github.com/SchwarzIT/api-linter-rules.git
4. Install the dependencies: pnpm install