> ## Documentation Index
> Fetch the complete documentation index at: https://docs.holydocs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# holydocs openapi-check

Validate an OpenAPI specification for compatibility with the HolyDocs renderer.

## 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:

```
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
```

```
Validating OpenAPI spec...

  Found 18 operations across 6 paths
  Found 8 schema definitions

3 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
```

```
Validating OpenAPI spec...

  Found 12 operations across 4 paths

2 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](https://github.com/Mermade/oas-kit).

## 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:

```
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
# Good
paths:
  /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](/cli/generate) -- Generate API reference pages from a validated spec
- [holydocs check](/cli/check) -- Validate the full project including OpenAPI references
- [holydocs build](/cli/build) -- Build static HTML with rendered API reference pages