Skip to content

rapidoc validate

npx rapidoc validate openapi.yaml
npx rapidoc validate https://example.com/openapi.json
npx rapidoc validate # in a portal: every local spec in apis:, and the workflow files

rapidoc validate checks a spec strictly against the OpenAPI Specification (2.0, 3.0, 3.1 and 3.2):

  • Required fields and types, as the specification’s schema for that version defines them: info.version, a response’s description, type values, and so on.
  • Path parameters: every {name} in a path must be defined as a path parameter, on the path or on each operation (a $ref to a parameter counts).
  • $refs: each must point to something. Files reached through a relative $ref are checked too.

Each error names the file, line and column, and the JSON pointer of what’s wrong; an error inside a file reached through $ref points into that file:

🔍 orders: specs/orders.yaml
❌ 2 error(s):
specs/orders.yaml:3:1 must have required property 'version' (#/info)
specs/shared/responses.yaml:12:3 must have required property 'description' (#/NotFound)
Option Meaning
--format pretty | json | sarif pretty (default) for the terminal; json for scripts; sarif for GitHub code scanning. json and sarif print one document on stdout and nothing else.
--strict Fail on warnings too.
--remote Also fetch and check remote $refs (and, in a portal, remote specs in apis:). Without it they are skipped, with a warning for $refs. A spec given as a URL is always fetched.

It exits with code 1 when the spec has errors (or warnings, with --strict), so it can gate a pull request:

.github/workflows/api.yml
# in a job's steps:
- run: npx rapidoc validate openapi.yaml

To see the problems on the pull request itself, upload a SARIF report to GitHub code scanning:

.github/workflows/api.yml
permissions:
security-events: write
# in a job's steps:
- run: npx rapidoc validate openapi.yaml --format sarif > rapidoc.sarif || true
- uses: github/codeql-action/upload-sarif@v3
with:
sarif_file: rapidoc.sarif

Run without a file in a RapiDoc Portal folder, it validates every local spec in apis: and the workflow files. With @rapidoc/portal installed it also warns about operations without an operationId (their page URLs change when their summary is edited), and checks that each workflow’s steps resolve against your APIs.

Validating one file needs only @rapidoc/cli; validating a whole portal reads its config, so it needs @rapidoc/portal.

To check what makes a good reference beyond validity (summaries, examples, operationIds), use rapidoc lint, which runs this check first.