OpenAPI Setup

Holocron can generate API reference pages from an OpenAPI specification file. Point a tab at your spec and Holocron creates a page per endpoint, grouped by tag.

Ask AI about this page

Basic setup

Add an OpenAPI tab to your docs.json navigation:

json

12345678910111213141516{
  "navigation": {
    "tabs": [
      {
        "tab": "Documentation",
        "groups": [
          { "group": "Getting Started", "pages": ["index"] }
        ]
      },
      {
        "tab": "API Reference",
        "openapi": "openapi.json"
      }
    ]
  }
}

Place your openapi.json (or openapi.yaml) file at the project root. If you set pagesDir, Holocron checks pagesDir first, then falls back to the project root.

Multiple specs

Pass an array to combine multiple spec files:

json

1234{
  "tab": "API Reference",
  "openapi": ["openapi/v1.json", "openapi/v2.json"]
}

Custom base path

By default, generated pages appear under /api/ (e.g. /api/get-users). Change the prefix with base:

json

12345{
  "tab": "API Reference",
  "openapi": "openapi.json",
  "base": "/reference"
}

Now endpoints render at /reference/get-users instead.

A leading slash is optional: "/reference" and "reference" behave the same. Set base to "" for no prefix.

When mounting docs inside your own app via custom entry, set base to a docs/-prefixed slug like /docs/api so generated endpoints stay under /docs/* and don't collide with your real /api routes.

Mixing guides with endpoint pages

The basic setup above is dedicated mode: every endpoint is auto-grouped by tag. If you instead want to interleave hand-written pages (authentication, getting your API key, an overview) with specific endpoints, add a groups or pages array to the tab. This is selective mode.

In selective mode, each page entry is one of:

a normal MDX slug like guide/authentication → renders that MDX file
an endpoint reference like POST /users → renders the auto-generated endpoint page from the spec

json

12345678910111213141516171819{
  "tab": "API Reference",
  "openapi": "openapi.json",
  "groups": [
    {
      "group": "Getting Started",
      "pages": [
        "api/overview",
        "api/authentication",
        "POST /auth/login",
        "GET /users"
      ]
    },
    {
      "group": "Orders",
      "pages": ["api/orders-intro", "POST /orders"]
    }
  ]
}

The sidebar follows the exact order you write, so your authentication guide can sit right before the endpoints it explains:

bash

123456789API Reference
├─ Getting Started
│   ├─ Overview              ← api/overview.mdx
│   ├─ Authentication        ← api/authentication.mdx
│   ├─ POST /auth/login      ← generated endpoint page
│   └─ GET /users            ← generated endpoint page
└─ Orders
    ├─ Working with Orders   ← api/orders-intro.mdx
    └─ POST /orders          ← generated endpoint page

An endpoint reference matches the form METHOD /path (case-insensitive method). To pick a specific spec when you list several, prefix it with the file name: "v2.json POST /orders".

If an endpoint reference does not match any operation in the spec, the build fails with an error so typos surface immediately.

Intro page, then all endpoints

Listing every endpoint by hand is tedious. Add the special "..." entry to write a short intro and then auto-include all the remaining endpoints, grouped by tag, right after it:

json

12345{
  "tab": "API Reference",
  "openapi": "openapi.json",
  "pages": ["api/authentication", "..."]
}

This renders your api/authentication guide first, then expands every endpoint not listed elsewhere into top-level tag groups (always-visible sidebar sections, exactly like dedicated mode):

bash

1234567API Reference
├─ Authentication        ← api/authentication.mdx
├─ Users                 ← top-level group from "..." (tag: users)
│   ├─ GET  /users
│   └─ POST /users
└─ Orders                ← top-level group from "..." (tag: orders)
    └─ POST /orders

The tag groups are hoisted to the tab's top level so they render as separate sidebar sections, not collapsed sub-groups nested under your intro pages.

The "..." entry only expands endpoints you did not already reference explicitly, so you can pin a few important endpoints up top and let the rest fall in afterward. Only one "..." is allowed per tab.

Customize generated pages

Add x-holocron to an OpenAPI operation to override its generated page metadata, insert MDX content, or choose its URL.

yaml

12345678910111213141516paths:
  /users:
    post:
      summary: Create user
      x-holocron:
        metadata:
          title: Create a new user
          sidebarTitle: Create user
          description: Add a user to the current organization.
        content: |
          <Badge color="blue">1 Credit</Badge>

          <Note>
          User email addresses must be unique.
          </Note>
        href: /api-reference/users/create

The metadata object supports title, sidebarTitle, and description. The content field accepts Markdown and Holocron MDX components. Holocron renders it before the generated endpoint header, description, authorization, parameters, and request fields.

The optional href must be an internal path without a query string or hash. It replaces the normal method-and-path slug and does not use the tab's base prefix.

Use x-holocron for new specifications. It is the canonical extension and can gain Holocron-specific options in future releases.

Mintlify compatibility

Holocron treats x-mint as a compatibility alias for the same page overrides. Existing Mintlify specifications work without renaming the extension.

yaml

12345678paths:
  /users:
    post:
      x-mint:
        metadata:
          title: Create a new user
          sidebarTitle: Create user
        content: '<Badge color="blue">1 Credit</Badge>'

Some existing specifications put title, sidebarTitle, and description directly inside the extension. Holocron supports this legacy shape too. When direct fields and metadata both define a value, metadata wins.

If an operation defines both extensions, x-holocron wins field by field. Missing or invalid x-holocron fields fall back to valid x-mint values.

Controlling which routes appear in the spec

Holocron documents every operation in your OpenAPI spec. If your API has internal routes (admin endpoints, webhook receivers, internal service calls) that should not appear in the public docs, exclude them from the spec itself rather than trying to filter them in docs.json.

Most frameworks let you mark routes as hidden at the route definition level so they are omitted from the generated spec.

Spiceflow

Add hide: true to the route's detail object:

1234567891011121314151617181920212223242526272829303132333435import { Spiceflow } from 'spiceflow'
import { openapi } from 'spiceflow/openapi'
import { z } from 'zod'

const app = new Spiceflow()
  .use(openapi({ path: '/openapi.json' }))

  // This route appears in the spec
  .route({
    method: 'GET',
    path: '/api/v0/projects',
    detail: {
      summary: 'List projects',
      tags: ['Projects'],
    },
    response: { 200: z.object({ projects: z.array(z.string()) }) },
    async handler() {
      return { projects: [] }
    },
  })

  // This route is hidden from the spec
  .route({
    method: 'POST',
    path: '/api/v0/keys',
    detail: {
      hide: true,
      summary: 'Create API key',
      tags: ['Internal'],
    },
    request: z.object({ name: z.string() }),
    async handler() {
      return { id: '123' }
    },
  })

A good rule of thumb: if a route requires session auth or internal tokens that your API consumers never have, hide it from the spec. Only document routes that work with the auth method your users actually use (e.g. API keys).

Other frameworks

Most OpenAPI generators support similar exclusion mechanisms:

Hono (@hono/zod-openapi): omit the route from the OpenAPI app, or don't register it with createRoute
FastAPI: set include_in_schema=False on the route decorator
Express (swagger-jsdoc): omit the JSDoc @openapi annotation from the route

The key idea is the same: your OpenAPI spec should only contain routes your API consumers can actually call. Internal, admin, or webhook routes belong in a separate spec or no spec at all.

How pages are generated

In dedicated mode, Holocron reads the spec and creates one page per operation (path + method). Pages are grouped by the tags field on each operation. The sidebar shows tag groups with individual endpoint pages.

Each generated page shows:

HTTP method and path
Description from the spec
Request parameters, headers, and body schema
Response schemas with status codes