OpenAPI Document Linting

TIP

For editing the lint.yaml file, Speakeasy's VSCode extension (opens in a new tab) provides syntax highlighting and autocompletion for the file, in addition to linting for OpenAPI documents, and our other supported file types.

In addition to running validation, you can use Speakeasy to lint your OpenAPI documents to ensure they are stylistically valid. By default, the linter runs using a recommended set of rules, which you can optionally extend with the available ruleset. Additionally you may write your own custom rules using the Spectral format.

With the Speakeasy Linter, you can:

• Lint & validate OpenAPI 3.x documents
• Choose from 70+ rules
• Get started quickly with 5 out-of-the-box rulesets including speakeasy-recommended, speakeasy-generation, speakeasy-openapi, vacuum & owasp
• Reconfigure Speakeasy's default rules & rulesets
• Configure custom rulesets
• Define new rules via the Spectral rule format
• Provide custom functions written in Go and JS for custom rules

Usage

There are three options for running linting:

1. Run manually via the Speakeasy CLI:

2. Integrate into your Speakeasy workflow:

then running speakeasy run will lint your document as part of the workflow.

This will generate a HTML report that you can find by clicking on the link output by the command.

3. In your IDE via Speakeasy's VSCode extension (opens in a new tab)

By default these options use the speakeasy-recommended ruleset to ensure your OpenAPI document meets Speakeasy's quality bar.

Configuration

Linting of an OpenAPI spec is fully configurable. You may create a custom ruleset by picking & choosing from our pre-defined sets or writing you own rules. Your custom linting rules can be used throughout your workflow.

The only exception is immediately prior to SDK generation. In that case, the speakeasy-generation ruleset is always used, to ensure compatibility with the code generator.

This is done through setting up a lint.yaml document in your .speakeasy folder, the folder can either live alongside your openapi document, or in the working directory you are running the speakeasy lint or speakeasy run commands from or in your home directory.

An example linting configuration (lint.yaml) is shown below:

A lint.yaml document defines a set of rulesets that can be chained together or used independently. These can define any of our built-in rulesets or any other rulesets defined in the document along with defining new rules to add or existing rules to modify or even just remixing our available rules to only run the ones you need.

Rulesets can be used in a number of different ways:

1. Set the defaultRuleset in your lint.yaml to the ruleset you want to use by default when this file is present. This will be used if a ruleset is not specified using the other options below.
2. Pass the ruleset name to the lint command with the -r argument for example speakeasy lint openapi -r barRuleset -s openapi.yaml.
3. Define the ruleset to use for a particular source in your workflow.yaml file.

Custom rules

The easiest way to define a custom rule is to use the Spectral rule format (opens in a new tab). This is an object that defines the rule and its properties.

This format can be used to override any of the builtin rules or to define new rules.

If you need to do anything more complex then matching a pattern or checking a field exists, then you can define a custom function in Go or JS and use that in your rule.

Speakeasy linting is built on top of Vacuum (opens in a new tab) and allows for provding custom functions to be used in rules. These can be written in Go or JS and then used in your rules. Documentation on how to write these functions can be found in the Vacuum documentation for JS (opens in a new tab) and Go (opens in a new tab)

Available Rules

Below is a list of all the available rules available to the Speakeasy Linter. These can be used in your custom rulesets or can be used to match and modify the default rules in your lint.yaml file.

Available Rulesets

Below is a list of all the available rulesets available to the Speakeasy Linter. These can be chained in your custom rules but get used by default when a custom linting configuration is not provided.

speakeasy-recommended

The speakeasy-recommended ruleset is the default ruleset used by the Speakeasy Linter when no custom ruleset is provided. It is a set of rules that are recommended to be used to ensure your OpenAPI document meets Speakeasy's quality bar.

speakeasy-generation

The speakeasy-generation ruleset is used when generating an SDK from an OpenAPI document. It is a set of rules that must pass to be able to successfully generate an SDK from your OpenAPI document. This ruleset when using the generator can't be overridden or reconfigured.

But you can use it as you see fit when configuring the linter to ensure your document is ready for generation.

speakeasy-openapi

The speakeasy-openapi ruleset is a minimal set of rules that are recommended to be used to ensure your OpenAPI is generally valid and ready to be used by a majority of the OpenAPI ecosystem.

vacuum

The vacuum ruleset is provided by the Vacuum project (opens in a new tab) which the Speakeasy Linter is built on top of. It is a set of rules that are recommended to be used to ensure your OpenAPI document meets Vacuum's quality bar.

owasp

The owasp ruleset is a set of rules that are recommended to be used to ensure your OpenAPI document meets the Open Worldwide Application Security Project (OWASP) (opens in a new tab) quality bar.