API references

Point docs.json at an OpenAPI spec and the engine generates a complete reference: a categorized sidebar, a page per operation with an interactive playground, and room for your hand-written pages alongside the generated ones. This site's demo reference is a live example.

The minimum

{
  "products": [{ "id": "payments", "label": "Payments API" }],
  "openapi": {
    "apis": [
      {
        "product": "payments",
        "label": "Payments API",
        "specs": [{ "spec": "payments.json" }]
      }
    ]
  }
}

Drop payments.json into public/openapi/, and /payments/api-reference exists — sidebar, endpoint pages, playground.

Choose your shape

Every entry in apis is exactly one of three shapes — pick from what your API actually is:

Your API is...	Use	Readers get
One current surface	`specs`	A flat reference
Released in versions (v1, v2...)	`versions`	A version dropdown; old versions at `/{product}/{section}/{id}` with an "outdated" notice
Several related surfaces (per device, per region, per audience)	`groups`	A switcher between grouped sub-references

Details and examples: Versions and groups.

Where things mount

A reference lives at /{product}/{section} — section defaults to api-reference. One product can mount several references at different sections:

{ "product": "terminals", "section": "management-api", "label": "Management API", "specs": ["management.json"] }

That adds a second section tab, /terminals/management-api, beside the first — with its own sidebar and label. Two references may not share the same product + section.

In this chapter

Specs

Local files, remote URLs, and the per-spec options.

Versions and groups

Model versioned and multi-surface APIs.

Endpoint pages and the sidebar

Categories, sections, hand-written pages, the playground.