OpenAPI integration

How it works

Drop an OpenAPI 2.0 / 3.0 / 3.1 spec into your repo, point nookdocs.config.json at it, and NookDocs auto-generates a full API reference for every endpoint. No template writing, no MDX per endpoint — the spec is the source of truth.

{
  "name": "Acme API",
  "api": {
    "openapi": "openapi.json",
    "playground": true
  },
  "navigation": [...]
}

URL pattern

Each endpoint becomes a page at:

/api-reference/{tag}/{operation-id}

The tag comes from the operation's tags[0] field (or default if none). The operation-id is the spec's operationId field (or a generated fallback like get-users-id if missing). Tags with spaces are slugified — "User Management" becomes user-management in the URL.

What's auto-generated

For every operation, the rendered page includes:

Supported spec versions

The parser uses @apidevtools/swagger-parser under the hood, which validates the spec and dereferences every $ref before we touch it. Invalid specs surface in your build log so you can fix them on the next push.

Schema features

Mixing manual MDX with auto-generated pages

The auto-generation only kicks in when there's no MDX page at the requested path. So you can override any auto-generated page by writing a manual MDX file at the same URL:

docs/api-reference/users/get-user.mdx

This wins over the auto-generated /api-reference/users/get-user. Use it when you want to add prose explanations, custom code examples, or migration notes that the spec alone can't express.

The recommended pattern: let auto-generation handle the bulk of your endpoints, write manual MDX only for the 5-10% that need extra context.

YAML and JSON

Both formats work. Point api.openapi at a .json, .yaml, or .yml spec and NookDocs parses it either way — YAML is a JSON superset, so you can keep your spec in whichever format your API framework emits (FastAPI, NestJS, Spring Boot, and most others emit either). No conversion step.

Configure once, deploy forever

After your first push with api.openapi configured, the sync job auto-runs on every subsequent push. Update your spec, commit, push — the API reference updates 30 seconds later. No manual rebuild step.

Try it

If you have a working OpenAPI spec, drop it at your docs base (relative to the base), add "api": { "openapi": "openapi.json" } to your nookdocs.config.json, and push. You'll have a fully-rendered API reference at /api-reference/{tag}/{operation-id} for every endpoint in your spec.

What's next