Spectral¶

# Install (Node)
npm install -g @stoplight/spectral-cli

# Lint a spec with the default ruleset
spectral lint openapi.json

# Lint with a custom ruleset
spectral lint openapi.yaml -r .spectral.yaml

Real talk: - Run it in CI on every PR that touches a spec - Fail the build on error severity, warn on the rest - -r points at your ruleset; defaults are fine for a first pass

# .spectral.yaml
extends: ["spectral:oas", "spectral:oas-ruleset"]

rules:
  no-numeric-ids:
    description: IDs must be UUIDs or strings, not integers
    given: $.paths.*.*.parameters[?(@.name == 'id')]
    severity: error
    then:
      field: schema
      function: pattern
      functionOptions:
        match: "^string$|^integer.*format: uuid$"

  security-defined:
    description: Every path must have a security scheme
    given: "$.paths[*][*]"
    severity: warn
    then:
      function: defined
      field: security

Why this works: - Rules use JSONPath to target spec locations (given) - function: defined/undefined/pattern cover most checks - Custom rules make the linter enforce your standards, not Stoplight's

Tips: - Package your ruleset (@scope/spectral-rules) and reuse across teams - Use spectral lint --fail-severity error in CI to block bad specs - Pair with the OpenAPI Generator to catch drift between spec and code

Gotchas: - Default ruleset doesn't check security — add OWASP-style rules yourself - JSONPath in given is finicky; test rules against a real spec first - Spectral won't catch a spec that doesn't match the implemented API — that's contract testing's job