Specs

A spec entry is either a filename in public/openapi/ or an http(s) URL. Strings work when you need no options; use the object form to shape how a spec renders.

"specs": [
  "simple.json",
  { "spec": "payments.json", "useFirstTagOnly": true },
  { "spec": "https://example.com/checkout-v70.json" }
]

Local vs remote

Local files live in public/openapi/ and version with your docs — predictable and reviewable. Remote URLs are fetched by fiskil openapi fetch (run automatically before dev and build) and cached under public/openapi/_remote/ with names suffixed by a hash of the URL, so two different URLs can even share a filename safely. Remote specs re-download only when missing or when you pass --force — a changed remote is not detected automatically, so refresh with fiskil openapi fetch --force; every spec, local or remote, is validated as parseable OpenAPI before the build proceeds.

Pin remote URLs to a version or commit (not a moving main) so your docs don't change under you between builds.

Per-spec options

Option	Type	Effect
`useFirstTagOnly`	boolean	Group each operation under its first tag only — the fix for specs that tag operations with both a resource and a version or audience tag
`mergeAs`	string	Collapse every tag into one sidebar category with this label — for small specs that don't need categories
`categoryOrder`	string[]	Pin these categories first, in this order; unlisted ones follow
`section`	string	Place all of this spec's categories under a labeled sidebar section (a `---Label---` from your `meta.json`)
`sectionByTag`	object	Route operations carrying a given tag into a section — and stop that tag being a category itself

The last two are the bridge between generated categories and your hand-authored sidebar structure — see Endpoint pages for the full picture.

How categories form

Operations group by tag into sidebar categories. Version-shaped tags (v3, v1.2) are ignored as categories, names are prettified (camelCase and dashes become words, short acronyms stay uppercase), duplicate operations de-duplicate by operationId, and operationIds carrying # separators become clean, stable page slugs automatically. A spec with no usable tags renders as a single "Uncategorized" group (give it mergeAs for a better label).