How to Validate OpenAPI Specs in GitHub Actions

A drifted OpenAPI spec silently breaks generated clients and docs; CI validation keeps the contract honest.

Run a linter such as @stoplight/spectral-cli or @redocly/cli lint against your spec file so style and structural errors fail the job.

Steps

• Add a ruleset (e.g. .spectral.yaml) extending spectral:oas.
• Install the linter in CI.
• Run it against your openapi.yaml.
• Let a non-zero exit fail the pull request.

Workflow

name: Validate OpenAPI
on:
  pull_request:
    paths: ['openapi.yaml', '.spectral.yaml']
jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '20' }
      - run: npx @stoplight/spectral-cli lint openapi.yaml --fail-severity=warn

Notes

• Scope the trigger with paths so it only runs when the spec or ruleset changes.
• Use --fail-severity=warn to treat warnings as failures and keep the spec clean.

Related guides