Hands-on with Spectral: Using API linting for better API design and API governance

Spectral is an open-source API linting tool (powered by Stoplight) that allows users to write rules which then can be used to check API descriptions. Typically, these would be in description languages such as OpenAPI, AsyncAPI, or Swagger. If you’re interested in an overview and an introduction, check out this interview with Spectral maintainer Phil Sturgeon where he walks us through the history of Spectral, what it does, and how it can be used.

Seven steps

In this article and presentation, we’re diving a bit deeper. Axway Catalyst, Chris Wood walks us through seven steps in which you can learn how to use Spectral for an increasingly powerful set of tasks. This means you can start making Spectral part of your API platform and your API governance with very little effort and can level up the way you’re using it over time.

At its core, Spectral is very simple: As input, it takes an API description (OpenAPI, AsyncAPI, Swagger, …) and a set of rules, and then checks whether the API description follows the rules. This can help with automating API guidelines to some extent and depending on how much effort you put into it, you can check for rather basic things such as that every resource should have a description associated with it, or you can get more sophisticated to cover more of your API guidelines.

If you’re interested in working through the examples, all demo code used in the video is freely available on GitHub to get you started. For a full presentation on how everything works please check out the video, in this blog post we simply walk you through what the individual steps are doing.

1. Out of the box. Spectral comes with built-in rules that go beyond what the API specifications require. This means that you can use Spectral out of the box without adding any rules yourself. You then get the result of checking API descriptions about Spectral’s default rules, and that can already catch some issues with API descriptions.

spectral lint examples/petstore-openapi-scenario-1.yaml

1. Create/extend rulesets. Many users want to change and/or add rules, and for this Spectral allows to specify additional rulesets. Using Spectral this way now allows you to specify additional rulesets that Spectral will use to check your API descriptions.

spectral lint --ruleset rulesets/petstore-scenario-2.yaml examples/petstore-openapi-scenario-2.yaml

1. Turning off rules. Some rules of rulesets that you are using may not be to your liking. For this case, Spectral supports selectively switching off certain rules. This means that you can use an existing ruleset without changing it, but you can still control how it’s used by switching off certain rules.
   extends:

extends:
  - ./petstore-scenario-2.yaml
rules:
  operation-description: off
  oas3-unused-components-schema: off

1. Built-in functions. Spectral has a number of built-in functions which you can use to implement rules yourself. These functions allow you to perform operations and will return success or failure results. In this example, we’re using a regular expression function for matching a string against a regular expression.

extends:
  - ./petstore-scenario-3.yaml
rules:
  hyphen-delimited-uris:
    message: "Words in the path must be lowercase and delimited by a hyphen or concatenated, or be a path parameter"
    severity: error
    given: "$.paths[*]~"
    then:
      function: pattern
      functionOptions:
        match: "^(?:\/(?:[a-z]+(?:-[a-z]+|)+|\\{[a-zA-Z]+\\}))+$"

1. Custom functions. If what you want to check in a rule is not covered by Spectral’s features or built-in functions, you can write your own functions (which have to be implemented in JavaScript). You can then use these custom functions in rules in the same way as built-in functions.

extends:
  - ./petstore-scenario-4.yaml
functions: [responses]
rules:
  operation-2xx-response: off
  default-response-fallback:
    message: "Response object does not have 2xx operation or default set"
    given: "$.paths.[*].[*].responses"
    severity: error
    then:
      function: responses

1. Organization-level rulesets. Moving on from using Spectral individually, the next step is to manage rulesets so that they are organized to be applied by different teams, and possible for different types of APIs (e.g., private/partner/public) or for different maturity stages of APIs (e.g., prototype vs. publicly available). This is where Spectral becomes a powerful tool for API governance, making it possible for an organization to encode and check guidelines in a way that can be incorporated into development processes.
2. Automating Spectral. Building on the previous point, the last point now is to make Spectral checks part of your development pipelines, meaning that checks will be done automatically every time you make changes to the API descriptions. This means that there is no time-consuming manual review process, and teams get alerted of problems with the API descriptions as quickly as possible.

These are the seven steps how you can take Spectral from a simple out-of-the-box tool to one that can help with API governance and API guidelines. The nice aspect here is that getting started is as simple as installing Spectral, and all other steps then can be done when necessary.

If you are interested in more details covered in the full presentation, here’s Chris Wood walking you through all the steps, the code from the GitHub demo repository, and explaining more details along the way.