OpenAPI

Point the engine at an OpenAPI file and it generates a full reference — one page per endpoint, with schemas, code samples, and a playground. This template ships one, mounted at /example/api-reference.

Add a spec

Drop your spec into public/openapi/ (JSON or YAML both work) and reference it in docs.json:

{
  "openapi": {
    "apis": [
      {
        "product": "example",
        "label": "Example API",
        "specs": [{ "spec": "example-api.json" }]
      }
    ]
  }
}

Remote specs work too — give a URL as spec and fetch/cache it with fiskil openapi fetch.

Tags & grouping

Endpoints are grouped in the sidebar by their OpenAPI tags. A few per-spec options tune that:

{
  "spec": "example-api.json",
  "useFirstTagOnly": true,
  "categoryOrder": ["Books", "Authors"],
  "mergeAs": "Endpoints"
}

• useFirstTagOnly — group each operation under its first tag only.
• categoryOrder — pin groups to the front in this order; the rest follow.
• mergeAs — collapse every tag into a single named group.
• sectionByTag — map tags to sidebar section headings for large specs.

Versions

Offer multiple API versions with a version switcher. The default version lives at the bare URL; others nest under their id:

{
  "product": "example",
  "label": "Example API",
  "versions": [
    { "id": "v2", "label": "v2", "default": true, "specs": [{ "spec": "example-v2.json" }] },
    { "id": "v1", "label": "v1", "specs": [{ "spec": "example-v1.json" }] }
  ]
}

Schema groups

When one reference covers several distinct schemas (say CDR and FDX), use groups for a switcher between them:

{
  "product": "example",
  "label": "Data API",
  "groupDisplay": "dropdown",
  "groups": [
    { "id": "cdr", "label": "CDR", "specs": [{ "spec": "cdr.json" }] },
    { "id": "fdx", "label": "FDX", "specs": [{ "spec": "fdx.json" }] }
  ]
}

Endpoint notes

Unknown OpenAPI fields are ignored during generation, so to add a prose note to a generated endpoint page, add x-fiskil-notice to the operation in your spec. It renders as a callout above the endpoint:

"x-fiskil-notice": "This endpoint is in beta and may change."

Or control the style:

"x-fiskil-notice": { "type": "warning", "text": "Not available yet." }