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, 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. You can also write custom rules using the Spectral format.

With the Speakeasy Linter, you can:

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

Usage

There are three options for running linting:

1. Run manually via the Speakeasy CLI:

speakeasy lint openapi -s openapi.yaml

2. Integrate into your Speakeasy workflow:

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

Running speakeasy run will lint your document as part of the workflow and generate an HTML report that you can access from a link in the command output.

3. Use the Speakeasy VS Code extension (opens in a new tab) in your IDE.

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

Configuration

The linting of an OpenAPI spec is fully configurable. You can create a custom ruleset by selecting from our predefined sets or writing your own rules. These custom linting rules can be used throughout your workflow.

However, immediately before SDK generation, the speakeasy-generation ruleset is always used 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 you run the speakeasy lint or speakeasy run commands from, or the home directory.

Here is an example of 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
      - ourRuleset
    rules:
      validate-enums: {
          severity: warn, # drop the severity of the `validate-enums` rule as I don't want this to block the pipeline
        }
  ourRuleset:
    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. You can define any built-in Speakeasy rulesets, define new rules, modify existing rules, or remix the available rules to suit your needs.

Rulesets can be used in various ways:

1. Set the defaultRuleset in your lint.yaml to the ruleset you want to use by default. The default ruleset will be used if a ruleset is not 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 to use for a particular source in your workflow.yaml file.

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

Custom rules

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

Use this format to override built-in rules or define new rules.

For rules that are more complex than matching a pattern or checking that a field exists, you can define a custom Go or JavaScript function in your rule.

Speakeasy linting is built on top of vacuum (opens in a new tab) and allows you to use custom Go or JavaScript functions in rules. The vacuum documentation provides instructions for writing custom functions in JavaScript (opens in a new tab) and Go (opens in a new tab).

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 your 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 your OpenAPI document meets 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 your OpenAPI document is 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 your OpenAPI document meets the vacuum quality bar.

owasp

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