Skip to Content
onedef

API docs

An API reference generated from the contract, as an OpenAPI document or a Mintlify site.

The OpenAPI document is always there, at /api/openapi.json (see REST). Point any OpenAPI viewer at it, such as Scalar, Redoc or Swagger UI.

To generate a full docs site instead, use @onedef/docs. It writes a Mintlify site from the contract at build time, with no running server:

scripts/docs.ts
import { writeMintlifySite } from '@onedef/docs'
import { generateOpenApi } from '@onedef/orpc'
import { contract } from '../lib/contract'

const spec = await generateOpenApi(contract, { servers: [{ url: 'https://api.acme.dev' }] })

await writeMintlifySite(contract, {
  dir: new URL('../docs', import.meta.url),
  name: 'Acme',
  spec,
})

Each service becomes a page, with its description as the intro and one entry per operation.

To leave some fields or operations out of public docs, generate them from forMode(contract, 'public'), a version of the contract that only shows what that credential mode may see.