Linting API Specs with Spectral

Spectral lints OpenAPI and AsyncAPI documents with built-in rules (valid spec, operationIds, descriptions) and custom rules that encode your style guide: casing, pagination parameters, Problem Details errors, security on every operation, no verbs in paths. Run it in editors and CI; use severity levels (error blocks merges, warn educates). Publish a shared ruleset package so every team uses the same rules.

# .spectral.yaml
extends: ["spectral:oas", "https://example.com/api-rules/ruleset.yaml"]
rules:
  operation-security-defined:
    description: Every operation must declare security
    given: "$.paths[*][get,post,put,patch,delete]"
    severity: error
    then: { field: security, function: truthy }
  no-verbs-in-paths:
    given: "$.paths[*]~"
    severity: warn
    then: { function: pattern, functionOptions: { notMatch: "/(get|create|update|delete)[A-Z/]" } }
  operation-id-camel-case:
    description: operationIds become SDK method names
    given: "$.paths[*][*].operationId"
    severity: error
    then: { function: casing, functionOptions: { type: camel } }

Common pitfalls

• Hundreds of noisy warnings everyone ignores.
• Rules without explanations or links to the guide.
• Linting only at release time instead of every PR.

Key points

• Encode the style guide as rules
• Errors block, warnings teach
• Shared ruleset across teams

Further reading: Spectral documentation