rapidoc validate
npx rapidoc validate openapi.yamlnpx rapidoc validate https://example.com/openapi.jsonnpx rapidoc validate # in a portal: every local spec in apis:, and the workflow filesrapidoc 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’sdescription,typevalues, and so on. - Path parameters: every
{name}in a path must be defined as apathparameter, on the path or on each operation (a$refto a parameter counts). $refs: each must point to something. Files reached through a relative$refare 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)Options
Section titled “Options”| 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:
# in a job's steps:- run: npx rapidoc validate openapi.yamlTo see the problems on the pull request itself, upload a SARIF report to GitHub code scanning:
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.sarifIn a portal
Section titled “In a portal”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.