Validate your OpenAPI spec and detect breaking changes on every pull request. Posts a detailed PR comment with errors, warnings, and an API diff — in seconds, no Docker required.
Supports OpenAPI 3.0, 3.1, 3.2 and Swagger 2.0. Free for public repos.
Validates against the OpenAPI 3.0, 3.1, 3.2 and Swagger 2.0 specifications. Returns structured errors with line numbers and JSON pointers.
Diffs the PR spec against your base branch and flags removed endpoints, new required fields, schema regressions and auth changes.
Posts a single, updating PR comment with a validation report, change summary and per-error details. No noisy reviewer floods.
Pure JavaScript action — cold-starts in ~1 second on hosted runners. No image pulls, no JVM, no Python toolchain.
Use as a required status check to prevent invalid specs — or breaking changes — from ever reaching main.
Public repos: unlimited validations, no account, no API key. Private repos use a free API key with a generous quota.
Drop this file into .github/workflows/ and you're done.
name: OpenAPI Check
on:
pull_request:
paths:
- 'openapi.yaml'
- 'openapi.json'
- 'docs/api/**'
permissions:
contents: read
pull-requests: write
jobs:
validate:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- uses: apinotes/openapi-validate@v1
with:
spec-path: 'openapi.yaml'
- uses: apinotes/openapi-validate@v1
with:
api-key: ${{ secrets.APINOTES_API_KEY }}
spec-path: 'openapi.yaml'
Create a free key at apinotes.io → Dashboard → Settings → API Keys, then store it as APINOTES_API_KEY in your repo secrets.
A single, structured comment — no email noise, no separate dashboards.
| File | openapi.yaml |
| Status | Valid |
| OpenAPI Version | 3.1 |
| Errors | 0 |
| Warnings | 2 |
| ➕ Added endpoints | 2 |
| ✏️ Changed endpoints | 1 |
| ➖ Removed endpoints | 0 |
| ⚠️ Breaking changes | 1 |
Built on the same engine that powers our online OpenAPI diff tool. Every change is classified by severity so reviewers can focus on what matters.
| Input | Default | Required | Description |
|---|---|---|---|
| spec-path | openapi.yaml | Yes | Path to your OpenAPI specification file (YAML or JSON). |
| api-key | — | Private repos only | Your ApiNotes API key, stored as a GitHub secret. |
| diff-enabled | true | No | Diff against the base branch and report breaking changes. |
| fail-on-errors | true | No | Fail the workflow if the spec contains validation errors. |
| fail-on-breaking | false | No | Fail the workflow when breaking changes are detected. |
| comment-on-pr | true | No | Post the validation report as a PR comment. |
Make the action a required status check to enforce a clean OpenAPI spec on main. Optionally fail the build when breaking changes are detected.
mainvalidate jobfail-on-breaking: true in your workflow to also block breaking changes Most teams stitch together openapi-spec-validator, oasdiff or openapi-diff, plus a custom GitHub script for PR comments. This action does it in one step.
| Capability | openapi-spec-validator | oasdiff / openapi-diff | ApiNotes Action |
|---|---|---|---|
| OpenAPI 3.0 / 3.1 / 3.2 validation | ✅ partial | ❌ | ✅ |
| Swagger 2.0 support | ✅ | ✅ | ✅ |
| Breaking change detection | ❌ | ✅ | ✅ |
| PR comments out of the box | ❌ | ❌ | ✅ |
| No Docker / no JVM | ✅ | ❌ (oasdiff Go binary) | ✅ |
| One step in workflow | ❌ (multi-step) | ❌ (multi-step) | ✅ |
| Free for public repos | ✅ | ✅ | ✅ |
Free for public repos forever. Generous free tier for private repos.
Free
Public repositories
Free
Private repositories
$6.99/mo
Private repositories
openapi-spec-validator or Swagger Editor) and diffs it against your base branch (like oasdiff / openapi-diff), then posts a single, structured PR comment. You don't need to glue together multiple tools.fetch-depth: 0 in actions/checkout so the base ref is available.fail-on-breaking: true). Add the job as a required status check in your branch protection rules and bad PRs cannot be merged.Catch invalid OpenAPI specs and breaking changes before they reach production. Install the action in 30 seconds.