Introduction – What is Spectral?
Spectral is an open source JSON/YAML linter developed by Spotlight. It comes with built in OpenAPI support straight out of the box, along with the ability to define custom rulesets. Spectral can also be used as a governance and style linter for your API documents, enabling you to enforce standards, maintain consistency, and, crucially, validate the security of your API specifications.
It’s completely free to use and even has a Visual Studio Code extension, allowing for real-time linting directly within the IDE.
In this blog, I’ll cover how to use Spectral, the key benefits, and how it integrates with your Azure estate and workflows. I’ve also created a free demo on GitHub that you can fork and explore, showing examples of both well-formed and poorly-formed API documents as they’re processed through Spectral linting.
Getting started
To get started with Spectral you have two options:
Install Spectral via CLI or VS Code Extension:
Option 1: CLI Installation
npm install -g @stoplight/spectral-cliOption 2: VS Code Extension Install the Spectral VS Code Extension for real-time linting on type or save.
Configuration file
Spectral uses a root configuration named spectral.yml, which sits in the root of your Git repository. This file defines the rulesets Spectral uses and can be aligned to standards such as OpenAPI—either including all available rules or only the recommended ones. Similar rulesets, such as AsyncAPI, are also supported. These rulesets are added to the YAML configuration file like so:
extends: [ [ "spectral:oas", "recommended" ], "https://unpkg.com/@stoplight/spectral-owasp-ruleset/dist/ruleset.mjs" ]Check it out here: https://github.com/riosengineer/spectral-demo/blob/main/.spectral.yml
Custom rules
Spectral excels at custom rulesets. You can create and design rules tailored to your organisation’s needs for API design and style. Spectral is widely used by large enterprises—including Microsoft and Adidas. In fact, Adidas have published their API guidelines using Spectral, which you can view here: api-guidelines/.spectral.yml at master · adidas/api-guidelines
As demonstrated in the Adidas Spectral ruleset, you can create powerful guidelines for your APIs to follow.
In my demo GitHub repository, I’ve included a sample custom rule, along with an example API specification that deliberately fails against it, so you can see a custom rule in action and how Spectral reports it during linting.
To add custom rules, simply append them beneath the extends property like so:
extends: [ [ "spectral:oas", "recommended" ], "https://unpkg.com/@stoplight/spectral-owasp-ruleset/dist/ruleset.mjs" ]
rules:
request-GET-no-body:
description: "A 'GET' request MUST NOT accept a 'body' parameter"
severity: error
given: $.paths..get.parameters..in
then:
function: pattern
functionOptions:
notMatch: "/^body$/"In my demo sample custom rule I’m looking to catch any API specifications that allow a body parameter for GET requests, which should be an invalid operation. You can check this in action further below.
Running Spectral
There are several ways to run Spectral. Like most modern tools, it offers a CLI, a Visual Studio Code extension, and even a GitHub Action, allowing you to shift left and lint your API specifications locally before merging to main.
Locally
In this example, I’m running Spectral locally in Visual Studio Code using the Spectral CLI, with the demo files from my GitHub repository. When you run the command below, Spectral will load the root configuration file, extend any defined rulesets, and run them against the YAML or JSON file for linting.
If you’re not running the command from the root of the repository, you can use the --ruleset flag to specify the path to your spectral.yml configuration file.
spectral lint file.jsonâś… Good API example
In my GitHub repository, I’ve included a well formed API specification file, available in both YAML and JSON formats that passes all the OpenAPI v3 and OWASP rulesets. When run through the CLI, the output confirms this in the terminal:
❌ Bad API example
The bad example file in the repository is included to show what not to do, and how Spectral linting can highlight multiple violations, from OpenAPI issues to OWASP rules that haven’t been met for security reasons.
VS Code extension
If you have the Visual Studio Code Spectral extension installed, you can lint in real time while developing. Issues will appear in the Problems window as you type, or you can configure the extension to lint on save instead:
Validating the custom rule
Checking the example custom rule I created is being caught as a linting violation from above:
spectral lint "apis/bad-example/openapi.json" | Select-String "request-GET-no-body"
âś… Success! The custom rule defined in the spectral.yml file is detecting a violation in my bad example API document. You can see this for yourself by cloning the GitHub repository and running the same command.
GitHub Action – CI
I’ve also set up a GitHub Workflow using the Spectral Action. You can fork the repository, make a minor change (for example, updating an operation description), raise a pull request, and see how Spectral lints and helps govern your API documents before they are merged into the main branch.
https://github.com/riosengineer/spectral-demo/blob/main/.github/workflows/spectral.yml
And you can see the linting has completed, highlighting the violations in the API document in the pull request annotations:
Azure & Spectral
You may be wondering how this could link into your Azure estate and workflows. Two major solutions come to mind when adopting Spectral as part of your CI and DevOps processes.
The first is APIOps, which I’ve previously blogged about here. This approach applies GitOps principles to API Management in Azure by bringing your APIs into Git. By doing this, you can run Spectral linting against your API specifications in the repository as part of your CI pipeline, ensuring developers and engineers adhere to the governance and standards defined by your organisation.
The second is Azure’s recently announced product, API Centre, which acts like a directory of all your organisation’s APIs. With API Centre’s self-managed option, you can lint all your organisation’s APIs using your Spectral configuration standards and easily monitor how compliant your APIs are across the entire organisation. This way, you can create a Spectral ruleset configuration and styling document that matches your organisational standards, and enforce these across your APIs centrally, highlighting any that are not in compliance.