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

Generate API reference MDX pages from an OpenAPI specification file.

## Usage

```bash
holydocs generate <spec-path> [options]
```

Reads an OpenAPI specification (JSON or YAML) and generates one MDX page per endpoint. Each generated page contains the appropriate `openapi` frontmatter directive so the HolyDocs renderer produces a full API reference layout with parameter tables, request/response schemas, and code samples.

## Arguments

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

## Options

| Option | Description | Default |
|---|---|---|
| `--output <dir>` | Output directory for generated pages (relative to project root) | `api-reference` |
| `--dir <path>` | Root directory of the docs project | Auto-detected |

## Examples

### Generate from a JSON Spec

```bash
holydocs generate openapi.json
```

Output:

```
Generating API reference pages...

✓ Parsed OpenAPI spec
Generated 24 API reference pages in api-reference/

Add to docs.json navigation:

{
  "group": "API Reference",
  "pages": [
    "api-reference/list-users",
    "api-reference/create-user",
    "api-reference/get-user",
    "api-reference/update-user",
    "api-reference/delete-user"
  ]
}
```

### Generate from a YAML Spec

```bash
holydocs generate ./specs/api.yaml
```

Both `.yaml` and `.yml` extensions are supported and parsed automatically.

### Custom Output Directory

```bash
holydocs generate openapi.json --output docs/api
```

Places the generated MDX files in `docs/api/` instead of the default `api-reference/`.

### Generate in a Specific Project

```bash
holydocs generate openapi.json --dir ./docs
```

## Generated Page Format

Each endpoint produces a minimal MDX file with `openapi` frontmatter:

```mdx
---
title: "List Users"
description: "Returns a paginated list of users in the organization."
openapi: "GET /v1/users"
---
```

The HolyDocs renderer reads the `openapi` frontmatter at build time and generates the complete API reference layout, including:

- HTTP method badge and endpoint path
- Request parameters (path, query, header, cookie)
- Request body schema with examples
- Response schemas for each status code
- Code samples in multiple languages
- Interactive API playground (in production)

The generated MDX files are intentionally minimal. All rendering logic lives in the HolyDocs renderer, so your pages automatically benefit from renderer updates without regenerating.

## Supported Spec Formats

| Format | Extensions | Version |
|---|---|---|
| OpenAPI | `.json`, `.yaml`, `.yml` | 3.0.x, 3.1.x |
| Swagger | `.json`, `.yaml`, `.yml` | 2.0 (converted internally) |

## Slug Generation

Page filenames are derived from the `operationId` field in your spec. The operationId is converted to a URL-friendly slug:

| operationId | Generated Filename |
|---|---|
| `listUsers` | `list-users.mdx` |
| `getUserById` | `get-user-by-id.mdx` |
| `createPaymentIntent` | `create-payment-intent.mdx` |

If an endpoint lacks an `operationId`, a slug is generated from the HTTP method and path:

| Endpoint | Generated Filename |
|---|---|
| `GET /v1/users` | `get--v1-users.mdx` |
| `POST /v1/payments` | `post--v1-payments.mdx` |

Endpoints without `operationId` produce less readable slugs. For the best results, ensure every operation in your spec has a unique `operationId`. Run `holydocs openapi-check` to identify missing operation IDs.

## Supported HTTP Methods

The generator processes endpoints for all standard HTTP methods:

- `GET`
- `POST`
- `PUT`
- `PATCH`
- `DELETE`
- `HEAD`
- `OPTIONS`

## Adding to Navigation

After generating pages, add them to your `docs.json` navigation. The command prints a ready-to-use JSON snippet:

```json
{
  "navigation": {
    "groups": [
      {
        "group": "API Reference",
        "pages": [
          "api-reference/list-users",
          "api-reference/create-user",
          "api-reference/get-user"
        ]
      }
    ]
  }
}
```

You can organize generated pages into multiple groups (e.g., "Users", "Payments", "Webhooks") by splitting the generated pages list in your `docs.json` navigation.

## Regenerating Pages

Running `holydocs generate` again overwrites existing files in the output directory. This is safe because the generated files contain only frontmatter. Any custom content you add below the frontmatter will be overwritten.

If you need to add custom content to API pages, add it in your MDX file below the frontmatter block. Then use version control to manage merges when regenerating.

## Related

- [holydocs openapi-check](/cli/openapi-check) -- Validate your OpenAPI spec before generating
- [holydocs build](/cli/build) -- Build static HTML including API reference pages
- [holydocs check](/cli/check) -- Validate all pages and links after generating