OpenAPI Integration

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 Usersopenapi: "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    }  }}

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"    }  }}

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.