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

# OpenAPI integration

Generate API reference documentation from OpenAPI specifications.

You can generate a complete API reference from an OpenAPI specification. Drop your spec file into your content directory, configure it in `docs.json`, and blode.md creates a page for every operation.

## Setup

  1. **Add your spec file**

Place an `openapi.yaml` or `openapi.json` file in your content directory:

      - docs/
        - docs.json
        - index.mdx
        - openapi.yaml
  1. **Configure in docs.json**

Add the `api.openapi` section to your `docs.json`:

    ```json title="docs.json"
    {
      "api": {
        "openapi": {
          "source": "openapi.yaml",
          "directory": "api"
        }
      }
    }
    ```
  1. **Deploy**

Run `blodemd push` and your API reference pages are generated automatically at `/api/{operation-id}`.

## Configuration options

- `source` (type: string, required: true): Path to your OpenAPI spec file, relative to the content directory.
- `directory` (type: string, default: "api"): URL path prefix for generated API pages. Defaults to "api".
- `include` (type: string[]): Filter which operations to include. Accepts an array of operation IDs or path patterns.
- `basePath` (type: string): Override the base path for API requests in the playground.

## Navigation

You can add your OpenAPI operations directly to the navigation by referencing the spec file in a navigation group:

```json title="docs.json"
{
  "navigation": {
    "groups": [
      {
        "group": "API Reference",
        "openapi": "openapi.yaml"
      }
    ]
  }
}
```

This automatically creates navigation entries for each operation in your spec, grouped by tag.

## API playground

Blode.md can render an interactive API playground alongside your documentation. Configure it with the `api.playground` option:

```json title="docs.json"
{
  "api": {
    "openapi": {
      "source": "openapi.yaml",
      "directory": "api"
    },
    "playground": {
      "display": "interactive",
      "proxy": "https://api.your-domain.test",
      "credentials": true
    }
  }
}
```

### Display modes

| Mode          | Behavior                                                            |
| ------------- | ------------------------------------------------------------------- |
| `interactive` | Full playground with editable parameters and a "Send" button.       |
| `simple`      | Read-only display of request and response examples.                 |
| `auth`        | Interactive playground that requires authentication before sending. |
| `none`        | No playground. Only the endpoint documentation is shown.            |

> [!TIP]
> Set `credentials: true` to include cookies and auth headers in playground
>   requests. Use `proxy` to route requests through your backend and avoid CORS
>   issues.