API docs (api-docs)

An interactive API reference at /docs, rendered by Scalar from the OpenAPI document your app already generates. Every resource, custom route, field rule and policy shows up without annotations.

npx calm add api-docs

Open http://localhost:5001/docs. The page loads /api/openapi.json and lets you browse and try every endpoint, with a session token as bearer authentication.

When it is served#

• In development and test mode: always.
• In production: only when the environment has API_DOCS=on.
• Never when openapi.enabled is false in the config.

calm add writes API_DOCS=on to .env and .env.example. If your production environment is built from .env.example, remove that line there (or set API_DOCS=off) unless you want a public reference in production.

Notes#

• The Scalar script is pinned to an exact version and loaded from jsDelivr (@scalar/api-reference@1.72.1). Change the SCALAR constant in the block to upgrade it, or self-host the file.
• The page has its own Content-Security-Policy, which allows that script and Scalar's fonts and nothing else.
• What the reference shows is what OpenAPI shows: hidden and write-only fields are not in output schemas, PUT aliases are not listed, and routes with hidden: true are left out. Each operation's description says who may call it (Access: owner | admin).