Skip to main content

Configuration

API reference

Configure your OpenAPI-backed API docs — base URL, spec location, playground, authentication, and request proxy.

NookDocs renders interactive API reference pages directly from your OpenAPI (or AsyncAPI) spec. Your config tells the renderer three things:

  1. Where the spec lives (api.openapi)

  2. Where real requests go (api.baseUrl)

  3. How the playground authenticates (api.auth)

Everything else — routing, try-it UI, schema flattening, code samples — the platform handles.

Quick start

{
  "api": {
    "baseUrl": "https://api.example.com/v1",
    "openapi": "openapi.json",
    "playground": "interactive",
    "auth": {
      "type": "bearer",
      "name": "Authorization"
    }
  }
}

Commit openapi.json to your docs base directory — the api.openapi path is relative to the base (the repo root for a single-repo project, or a subfolder for a monorepo). On next sync, every endpoint in the spec becomes a page under the navigation entries you reference via /api-reference/<tag>/<operation-id> paths (see Navigation for how to surface them in the sidebar).

Fields

api.baseUrlstring

Prefixed to every endpoint path in the generated pages + playground. Omit for specs whose servers[] already carries full URLs. If both are set, api.baseUrl wins.

api.openapistring | string[]

OpenAPI 3.x spec path — relative to your docs base (e.g. openapi.json) or absolute URL (https://api.example.com/openapi.json). Supports JSON and YAML. Pass an array to merge multiple specs into one reference tree.

api.asyncapistring | string[]

AsyncAPI 3.x spec (channels, pub/sub, WebSocket) — same path rules as openapi. Roadmap: the key is accepted and validated today, but no pages are generated from it yet. Set it now if you want the path recorded; nothing renders until support ships.

api.playground'interactive' | 'simple' | 'none'default: "interactive"
  • "interactive" — full "Try it" with live requests against baseUrl. Pre-fills auth headers, shows response bodies inline, copies as curl.

  • "simple" — form-preview only, no network. Useful for APIs with destructive endpoints or private environments. Roadmap

  • "none" — read-only docs. Skip the playground entirely; readers copy the snippet.

api.auth.type'bearer' | 'apiKey' | 'basic'

Pre-fills the auth header in the playground. Omit for public APIs.

api.auth.namestring

Header name. Default Authorization for bearer + basic. Explicit for apiKey (e.g. X-API-Key, X-Api-Token).

api.proxybooleandefault: false

Send Try-it requests from NookDocs instead of the reader's browser.

When you need the proxy

A Try-it request is a cross-origin call from your docs site to your API. Unless your API answers with Access-Control-Allow-Origin for that exact docs origin, the browser blocks the response before the page can read it — and the only thing the playground can show is Failed to fetch, with no status and no body.

The confusing part is that the same request succeeds from curl or Postman. Those tools do not enforce CORS; browsers do. So a working API can still produce a broken playground.

Two ways out:

  1. Send CORS headers for your docs domain. Best when you control the API and are happy for browsers to call it from that origin.

  2. Turn on api.proxy. The request is then made by NookDocs, which is not a browser, so CORS does not apply.

{
  "api": {
    "baseUrl": "https://api.acme.com",
    "proxy": true
  }
}

Proxied requests are restricted to api.baseUrl — same origin, and under its path. A URL outside it is refused, so the proxy cannot be used to reach anything else. Redirects are not followed, and the response is returned as the playground would have received it directly.

With the proxy on, credentials entered in the playground travel through NookDocs to reach your API. Leave it off if your API already allows your docs origin.

Multiple specs, one reference

Large APIs often split endpoints across files (public vs admin vs webhooks). Point openapi at an array:

{
  "api": {
    "openapi": [
      "specs/public.yaml",
      "specs/admin.yaml",
      "specs/webhooks.yaml"
    ]
  }
}

The platform merges them into one tree, tagged by operation. If two specs declare the same operationId, the LAST entry wins — we emit a build warning so you catch it.

Authentication in the playground

The playground reads api.auth and pre-fills the request headers:

  • bearer → Authorization: Bearer <token> with an input for the token.

  • apiKey → <name>: <key> with an input for the key.

  • basic → Authorization: Basic <base64(user:pass)> with inputs for user + pass.

The token — and path parameter values like a project id — carry over when the reader switches endpoints, so they only type them once per session. Both live only in the reader's browser (sessionStorage: cleared when the tab closes, never sent to our servers). For per-user personalized tokens, see Personalization (planned).

Navigation integration

API pages auto-slot into navigation groups that declare an openapi field. Example:

{
  "navigation": [
    {
      "tab": "API Reference",
      "groups": [
        {
          "group": "Projects",
          "openapi": "openapi.json",
          "pages": ["/api-reference/projects/list", "/api-reference/projects/create"]
        }
      ]
    }
  ]
}

The pages can reference auto-generated paths (/api-reference/<tag>/<operation-id>) or you can skip pages and the renderer auto-fills every endpoint that matches the group's openapi filter.

See the full Navigation reference for tab-scoped OpenAPI bindings, filtering by tag, and per-version API docs.

Troubleshooting

SDK code samples

NookDocs surfaces SDK usage directly in the per-endpoint code card (the right column on every API reference page). Reader picks a language tab and sees the real client.projects.list() call instead of a raw fetch example.

Source: the x-codeSamples OpenAPI extension — a ReDoc convention that Speakeasy, Stainless, and Fern all populate automatically when they generate SDKs. You can also hand-write samples directly in your spec.

paths:
  /projects:
    get:
      x-codeSamples:
        - lang: javascript
          label: Node.js
          source: |
            import { NookDocs } from "@nookdocs/sdk";
            const client = new NookDocs({ apiKey: process.env.CODIV_API_KEY });
            const projects = await client.projects.list();
        - lang: python
          source: |
            from nookdocs import Client
            client = Client(api_key=os.environ["CODIV_API_KEY"])
            projects = client.projects.list()

On the endpoint page the code card tab row becomes:

cURL · Node.js · SDK  |  Python · SDK  |  cURL · Python · JavaScript · PHP · Go · Java · Ruby
         ^ from x-codeSamples                ^ auto-generated HTTP templates

Tabs labeled "· SDK" come from the spec; the rest are our per-language HTTP templates as a fallback for languages the tenant didn't cover.

Supported lang values

langDisplayed asPrism grammar
javascript, typescriptJavaScript / TypeScriptjavascript / typescript
node, nodejsNode.jsjavascript
python, pyPythonpython
go, golangGogo
rubyRubyruby
phpPHPphp
javaJavajava
csharp, c#, dotnetC# / .NETcsharp
rustRustrust
swiftSwiftswift
kotlinKotlinkotlin
bash, shell, curlBash / cURLbash

Unknown slugs pass through verbatim and use the slug itself as both label and Prism grammar.

Label disambiguation

When a single language has multiple samples for the same endpoint (e.g. separate examples for "List unwatered plants" vs "List potted plants"), set label on each entry — the tab row shows the label instead of just the language name.

No config needed

x-codeSamples lives in the OpenAPI spec itself; the nookdocs.config.json#api block doesn't need any SDK-specific keys. Push the spec with samples, next sync picks them up, tabs appear automatically.

Was this page helpful?

Last updated September 17, 2026