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

# OpenAPI Integration

Import OpenAPI 3.x specifications to automatically generate API reference documentation with interactive playgrounds.

## Overview

HolyDocs parses OpenAPI 3.0 and 3.1 specifications at build time to generate fully interactive API reference pages. Each endpoint in your spec becomes a documentation page with request/response schemas, code samples, and an interactive playground.

## Adding an OpenAPI Spec

Reference your OpenAPI specification in `docs.json` using the `api` configuration:

```json
{
  "api": {
    "openapi": "https://api.yourcompany.com/openapi.json"
  }
}
```

You can also use a local file path relative to your docs root:

```json
{
  "api": {
    "openapi": "./openapi.yaml"
  }
}
```

### Multiple Specs

Merge multiple OpenAPI specs into a single API reference:

```json
{
  "api": {
    "openapi": [
      "https://api.yourcompany.com/v1/openapi.json",
      "https://api.yourcompany.com/v2/openapi.json"
    ]
  }
}
```

## Navigation Integration

### Automatic Page Generation

Use the `openapi` property on a navigation group to auto-generate pages from your spec:

```json
{
  "navigation": {
    "groups": [
      {
        "group": "Pet Store API",
        "openapi": {
          "source": "https://petstore3.swagger.io/api/v3/openapi.json",
          "directory": "api/petstore"
        },
        "pages": []
      }
    ]
  }
}
```

During build, the `pages` array is automatically filled with one page per API operation. Page slugs are generated from the operation summary or operation ID.

### Manual Page References

Alternatively, create individual MDX pages that reference specific operations:

```mdx
---
title: List Users
openapi: "GET /api/v1/users"
---
```

The `openapi` frontmatter field links the page to the matching operation in your spec.

## $ref Resolution

HolyDocs fully resolves `$ref` references in your OpenAPI spec, including:

- Local references (`$ref: '#/components/schemas/User'`)
- External file references (`$ref: './models/user.yaml'`)
- Remote URL references (`$ref: 'https://api.example.com/schemas/common.json#/Error'`)

OpenAPI parsing is performed at build time (not render time) to stay within Cloudflare Worker CPU limits. The parsed JSON is stored in R2 and used by the renderer to generate API pages.

## AsyncAPI Support

HolyDocs also supports AsyncAPI specifications for event-driven APIs:

```json
{
  "api": {
    "asyncapi": "https://api.yourcompany.com/asyncapi.yaml"
  }
}
```

AsyncAPI channels are rendered as documentation pages showing message schemas and channel bindings.

## Playground Configuration

Control how the API playground behaves:

```json
{
  "api": {
    "playground": {
      "display": "interactive",
      "proxy": true
    }
  }
}
```

| Option | Values | Description |
|---|---|---|
| `display` | `interactive` \| `simple` \| `none` | Interactive playground, simple examples only, or no playground |
| `proxy` | boolean | Route API requests through HolyDocs proxy to avoid CORS issues |

## Authentication in Specs

Configure how authentication is shown in API docs:

```json
{
  "api": {
    "mdx": {
      "auth": {
        "method": "bearer",
        "name": "Authorization"
      },
      "server": "https://api.yourcompany.com"
    }
  }
}
```

## Parameter Display

Control how request parameters are displayed:

```json
{
  "api": {
    "params": {
      "expanded": "all"
    }
  }
}
```

| Option | Values | Description |
|---|---|---|
| `expanded` | `all` \| `closed` | Show all parameters expanded or collapsed by default |

## Method Badges

API pages automatically display HTTP method badges (GET, POST, PUT, DELETE, PATCH) in the sidebar navigation. The badge color and label are derived from the operation's HTTP method. The method-to-page mapping is stored in `_pageMethodMap` during the build.