spectral:oas error on by default

oas3-server-variables

Server variables must be defined and valid and there must be no unused variables.

Applies to
serverservers
Selects
$.servers[*]
#PathItem.servers[*]
#OperationObject.servers[*]
#LinkObject.server
Function
serverVariables
Specs
OpenAPI 2.0OpenAPI 3.0OpenAPI 3.1OpenAPI 3.2
Message
{{error}}

Use it

This rule ships with OpenLint in spectral:oas. Extending the ruleset turns it on:

extends: spectral:oas
rules:
  oas3-server-variables: error   # or off, or another severity

Definition

As defined in @openlint/openlint-rulesets. Functions show by name.

oas3-server-variables:
  description: >-
    Server variables must be defined and valid and there must be no unused
    variables.
  message: '{{error}}'
  severity: 0
  recommended: true
  given:
    - '$.servers[*]'
    - '#PathItem.servers[*]'
    - '#OperationObject.servers[*]'
    - '#LinkObject.server'
  then:
    function: serverVariables
    functionOptions:
      checkSubstitutions: true
      requireDefault: true

About this rule

This rule ensures that server variables defined in OpenAPI Specification 3 (OAS3), 3.1, and 3.2 are valid, not unused, and result in a valid URL. Properly defining and using server variables is crucial for the accurate representation of API endpoints and preventing potential misconfigurations or security issues.

Bad Examples

  1. Missing definition for a URL variable:
servers:
  - url: "https://api.{region}.example.com/v1"
    variables:
      version:
        default: "v1"

In this example, the variable {region} in the URL is not defined within the variables object.

  1. Unused URL variable:
servers:
  - url: "https://api.example.com/v1"
    variables:
      region:
        default: "us-west"

Here, the variable region is defined but not used in the server URL.

  1. Invalid default value for an allowed value variable:
servers:
  - url: "https://api.{region}.example.com/v1"
    variables:
      region:
        default: "us-south"
        enum:
          - "us-west"
          - "us-east"

The default value ‘us-south’ isn’t one of the allowed values in the enum.

  1. Invalid resultant URL:
servers:
  - url: "https://api.example.com:{port}/v1"
    variables:
      port:
        default: "8o80"

Substituting the default value of {port} results in an invalid URL.

Good Example

servers:
  - url: "https://api.{region}.example.com/{version}"
    variables:
      region:
        default: "us-west"
        enum:
          - "us-west"
          - "us-east"
      version:
        default: "v1"

In this example, both {region} and {version} variables are properly defined and used in the server URL. Also, the default value for region is within the allowed values.

Sources