OpenAPI document linting

TIP

The    Speakeasy VS Code extension (opens in a new tab) provides syntax highlighting and autocompletion for editing the lint.yaml file, as well as linting for OpenAPI documents and other supported file types.

In addition to running validation, Speakeasy lints OpenAPI documents to ensure stylistic validity. By default, the linter runs using a recommended set of rules, which can be extended with the available ruleset. Custom rules can also be written using the Spectral format.

The Speakeasy Linter offers:

• Linting and validation of OpenAPI 3.x documents
• Access to 70+ rules
• Quick start with five out-the-box rulesets: speakeasy-recommended, speakeasy-generation, speakeasy-openapi, vacuum, and owasp
• Reconfiguration of Speakeasy default rules and rulesets
• Configuration of custom rulesets
• Definition of new rules using the Spectral rule format
• Support for custom functions written in Go and JavaScript

Usage

Three options are available for running linting:

1. Run manually via the Speakeasy CLI:

speakeasy lint openapi -s openapi.yaml

2. Integrate into a Speakeasy workflow:

workflowVersion: "1.0.0"
speakeasyVersion: latest
sources:
  api-source:
    inputs:
      - location: ./openapi.yaml

Running speakeasy run lints the document as part of the workflow and generates an HTML report accessible from a link in the command output.

By default, these options use the speakeasy-recommended ruleset to ensure OpenAPI documents meet the Speakeasy quality bar.

Configuration

OpenAPI spec linting is fully configurable. Create custom rulesets by selecting from predefined sets or writing new rules. These custom linting rules work throughout the workflow.

Immediately before SDK generation, the speakeasy-generation ruleset is always applied to ensure compatibility with the code generator.

Configure linting in a lint.yaml document in the .speakeasy folder. The .speakeasy folder can be located in the same directory as the OpenAPI document, the working directory for running the speakeasy lint or speakeasy run commands, or the home directory.

Example linting configuration in a lint.yaml file:

lintVersion: 1.0.0
defaultRuleset: speakeasyBarRuleset
rulesets:
  barRuleset:
    rulesets:
      - speakeasy-generation # Use the speakeasy-generation ruleset as a base
      - customRuleset
    rules:
      validate-enums: {
          severity: warn, # drop the severity of the `validate-enums` rule to avoid blocking the pipeline
        }
  customRuleset:
    rules:
      paths-kebab-case: # A custom rule following the spectral format for a rule
        description: Paths should be kebab-case.
        message: "{{property}} should be kebab-case (lower-case and separated with hyphens)"
        severity: warn
        given: $.paths[*]~
        then:
          functionOptions:
            match: "^(\\/|[a-z0-9-.]+|{[a-zA-Z0-9_]+})+$"
      contact-properties:
        description: Contact object must have "name", "url", and "email".
        given: $.info.contact
        severity: warn
        then:
          - field: name
            function: truthy
          - field: url
            function: truthy
          - field: email
            function: truthy

A lint.yaml document defines a collection of rulesets that can be chained together or used independently. Define any built-in Speakeasy rulesets, create new rules, modify existing rules, or remix available rules to suit specific needs.

Use rulesets in these ways:

1. Set the defaultRuleset in the lint.yaml to use by default. This ruleset applies when no ruleset is specified using the lint command or workflow.yaml file.
2. Pass a ruleset name to the lint command with the -r argument, for example, speakeasy lint openapi -r barRuleset -s openapi.yaml.
3. Define the ruleset for a particular source in the workflow.yaml file.

workflowVersion: "1.0.0"
speakeasyVersion: latest
sources:
  api-source:
    inputs:
      - location: ./openapi.yaml
    ruleset: barRuleset

Custom rules

Create custom rules most easily using the Spectral rule format (opens in a new tab), which defines the rule and its properties as an object.

This format works for overriding built-in rules or defining new rules.

For more complex rules beyond pattern matching or field existence checking, define custom Go or JavaScript functions.

Custom Go/JavaScript functions

Speakeasy linting builds on vacuum (opens in a new tab) and supports custom Go or JavaScript functions in rules. The vacuum documentation explains writing custom functions in JavaScript (opens in a new tab) and Go (opens in a new tab).

After creating custom functions, place them in a directory named functions in the .speakeasy folder (e.g. .speakeasy/functions/foo.js).

Available rules

The rules available to the Speakeasy Linter are listed below and can be used in custom rulesets or to match and modify default rules in the lint.yaml file.

Available rulesets

The rulesets available to the Speakeasy Linter are listed below and can be chained in custom rules. These rulesets will be used by default when custom linting configuration is not provided.

speakeasy-recommended

The Speakeasy Linter uses the speakeasy-recommended ruleset by default when no custom ruleset is provided. This ruleset is recommended to ensure OpenAPI documents meet the Speakeasy quality bar.

speakeasy-generation

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

Use the speakeasy-generation ruleset as appropriate to configure the linter to ensure an OpenAPI document is ready for generation.

speakeasy-openapi

The speakeasy-openapi ruleset is a minimal set of rules recommended to ensure OpenAPI documents are generally valid and ready to be used by most 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. This set of rules is recommended to ensure OpenAPI documents meet the vacuum quality bar.

owasp

The owasp ruleset is recommended to ensure OpenAPI documents meet the Open Worldwide Application Security Project (OWASP) (opens in a new tab) quality bar.