holydocs openapi-check

Usage

bash
holydocs openapi-check <spec-path>

Parses and validates an OpenAPI specification file, checking for structural errors, missing fields, and compatibility issues with the HolyDocs rendering pipeline. Reports errors (which block correct rendering) and warnings (which may cause suboptimal output).

Arguments

Argument	Description	Required
<spec-path>	Path to the OpenAPI specification file (.json, .yaml, or .yml)	Yes

Examples

Validate a JSON Spec

bash
holydocs openapi-check openapi.json

Output for a valid spec:

text
Validating OpenAPI spec...  Found 24 operations across 8 paths  Found 12 schema definitions✓ OpenAPI spec is valid!

Validate a YAML Spec

bash
holydocs openapi-check api.yaml

Spec with Warnings

bash
holydocs openapi-check openapi.json

text
Validating OpenAPI spec...  Found 18 operations across 6 paths  Found 8 schema definitions3 warning(s):  ⚠ GET /v1/users — missing operationId  ⚠ POST /v1/users — no summary or description  ⚠ No servers defined — API playground won't know the base URL⚠ Spec is usable but has warnings.

Spec with Errors

bash
holydocs openapi-check broken-spec.json

text
Validating OpenAPI spec...  Found 12 operations across 4 paths2 error(s):  ✗ Missing "info.title"  ✗ Duplicate operationId: "getUser"1 warning(s):  ⚠ DELETE /v1/users/{id} — no responses defined✗ Spec has errors that may prevent correct rendering.

Checks Performed

Structural Checks

Check	Severity	Description
Version field	Error	Spec must have an openapi, swagger, or asyncapi version field
Info object	Error	The info object must be present
Info title	Error	info.title is required
Info version	Warning	info.version should be present
Path prefix	Error	All paths must start with /

Operation Checks

Check	Severity	Description
operationId uniqueness	Error	No two operations can share the same operationId
operationId presence	Warning	Every operation should have an operationId for clean page slugs
Summary or description	Warning	Operations should have at least a summary or description
Responses defined	Warning	Operations should define at least one response

Compatibility Checks

Check	Severity	Description
OpenAPI version	Warning	HolyDocs fully supports 3.0.x and 3.1.x; Swagger 2.0 works but upgrading is recommended
Servers defined	Warning	Without servers, the API playground cannot determine the base URL
Schema definitions	Info	Reports the number of component schemas found
Unresolved $ref	Warning	External or relative $ref references that may not resolve

Swagger 2.0 specs are supported but may not render all features correctly. For the best results, convert to OpenAPI 3.0 or 3.1 using a tool like swagger2openapi.

Exit Codes

Code	Meaning
0	Spec is valid (no errors; warnings are allowed)
1	Spec has errors that may prevent correct rendering

Supported Formats

The command auto-detects the file format based on extension:

Extension	Parser
.json	JSON.parse
.yaml	YAML parser
.yml	YAML parser

If the file cannot be parsed, the command reports the parse error and exits:

text
Error: Failed to parse: Unexpected token at line 42

Common Issues

Missing operationId

The operationId field determines the generated page filename. Without it, holydocs generate produces less readable slugs:

yaml
# Goodpaths:  /users:    get:      operationId: listUsers      summary: List all users# Missing operationId — generates "get--users.mdx"paths:  /users:    get:      summary: List all users

No Servers Defined

The servers array tells the API playground which base URL to use for live requests. Without servers defined, the playground still renders but cannot send requests.

Unresolved $ref

External $ref references (pointing to other files or URLs) are flagged as potentially unresolved. Local $ref references within the same file (e.g., #/components/schemas/User) are not flagged, as they are resolved by the renderer at build time.

Run holydocs openapi-check before holydocs generate to catch issues early. Fixing warnings at the spec level produces cleaner API reference pages.

Related

• holydocs generate -- Generate API reference pages from a validated spec
• holydocs check -- Validate the full project including OpenAPI references
• holydocs build -- Build static HTML with rendered API reference pages