Get started →
ciderpress

    OpenAPI

    Drop an OpenAPI spec into your config and ciderpress generates a full API reference — overview page, per-operation pages, and sidebar entries.

    See the Petstore API Reference for a live example.

    Configuration

    Attach openapi to a Page (for top-level API docs) or to a Workspace (for per-package API docs). There is no top-level openapi field — the spec lives on the node it mounts under, so a config can describe more than one API at once without implicit cross-wiring.

    export default defineConfig({
  pages: [
    {
      title: 'API',
      path: '/api',
      openapi: {
        spec: 'openapi.json',
        path: '/api',
      },
    },
  ],
})
    OptionTypeRequiredDefaultDescription
    specstringyes—Path to the OpenAPI document (.json, .yaml, .yml), relative to repo root
    pathstringyes—URL path the API operation pages mount under (must start with /)
    titlestringno'API Reference'Sidebar group title and overview page heading
    sidebarLayout'method-path' | 'title'no'method-path'How operations appear in the sidebar

    When openapi is declared on a Workspace, the path must be nested under the workspace's own path — path: '/apps/api' plus openapi: { path: '/apps/api/reference' } works; openapi: { path: '/elsewhere' } fails validation.

    What gets generated

    During ciderpress sync, the spec is fully dereferenced (all $refs resolved) and three types of files are written:

    FileDescription
    {path}/openapi.jsonThe dereferenced spec as JSON
    {path}/index.mdxOverview page with API info, servers, auth schemes, and operation summary
    {path}/{operation}.mdxOne page per operation with full spec details and code examples

    Operations are extracted from paths, grouped by their first tag, and slugified from operationId. If no operationId exists, the slug is derived from the method and path.

    Overview page

    The overview page renders API title, version, description, server URLs, authentication schemes, and a summary of operations grouped by tag.

    https://docs.example.com/petstore

    OpenAPI overview page

    Operation page

    Each operation gets a two-column layout with spec details on the left (parameters, request body, responses, security) and auto-generated code examples on the right (cURL, JavaScript, Python, Go, Ruby, Java).

    https://docs.example.com/petstore/getpetbyid

    OpenAPI operation page

    method-path (default)

    Each sidebar entry shows a colored method badge and the path in monospace. Both screenshots above show this layout in the sidebar.

    title

    Each sidebar entry shows the operation's summary as plain text instead of the method and path.

    Per-workspace OpenAPI

    Attach an OpenAPI spec to any workspace for per-package API docs. The Workspace.openapi shape is identical to Page.openapi:

    ciderpress.config.ts
    export default defineConfig({
  workspaces: [
    {
      title: 'Services',
      icon: 'pixelarticons:server',
      items: [
        {
          title: '@acme/api',
          description: 'REST API service',
          path: '/packages/api',
          openapi: {
            spec: 'packages/api/openapi.yaml',
            path: '/packages/api/reference',
            title: 'API Reference',
            sidebarLayout: 'title',
          },
          pages: [{ title: 'Overview', path: '/packages/api', include: 'packages/api/README.md' }],
        },
      ],
    },
  ],
})

    References