@emeryld/rrroutes-openapi

@emeryld/rrroutes-openapi

RRRoutes docs + “try it” playground, shipped as static assets plus a thin Express helper. The UI is React-based and reads the serialized registry you provide (no OpenAPI YAML needed).

What you get

• React docs UI (filters, grouping, schema tables) with a built-in playground for hitting your endpoints.
• Express helper that mounts the docs page and serves the built assets.
• Playground inputs share a base URL and let you set custom request headers across calls.
• Escape hatches: supply your own React tree or prerendered HTML if you want full control.

Current UI features

• /routes/:endpointId is the canonical playground location – tab/layout state is encoded in the URL (?tab=metrics&layout=detailsMax) so deep links reopen the exact view.
• History ships with request overview charts, plus per-row DetailModals that merge request bodies, headers, cache hits, and logs.
• Endpoint Metrics includes a live request feed that reuses the History modal + replay button.
• Cache summary rows open a stacked timeline + “clear this key” modal, and application log rows open grouped modals that link straight to the related request when groupId ties back to a request.
• Presets let each operation include a human description plus “run this”/“run all” buttons; runs display status, duration, and expandable responses.
• Every major table (History, Logs, Cache logs/summary, Routes, Presets) exposes a consistent Export CSV action that reflects the current filters/sorting.

Quick start (Express)

import express from 'express'
import { finalize } from '@emeryld/rrroutes-contract'
import { mountRRRoutesDocs } from '@emeryld/rrroutes-openapi'
import { leaves } from './contract'

const registry = finalize(leaves)
const router = express.Router()

// Mounts page at /__rrroutes/docs and serves JS/CSS from /__rrroutes/docs/assets
mountRRRoutesDocs({
  router,
  leaves: registry.all,
  options: { path: '/__rrroutes/docs' },
})

Options (server)

• path (default /__rrroutes/docs): where the page is mounted.
• assetBasePath (default ${path}/assets): where the static JS/CSS are served from.
• csp (default true): emit a CSP header + nonce.
• auth: HTTP Basic auth for the docs + webhooks. Uses process.env.RRROUTES_DOCS_PASSWORD by default; set enabled: false to skip the guard.
• redactLogEntry: (entry) => entry | null hook to scrub or drop log entries before they hit the UI.
• onRequest: (ctx) => ({ leaves?, nonce?, html? }) hook to tweak leaves, override the nonce, or return a fully custom HTML response.

Render it yourself

If you want to control rendering:

import {
  createLeafDocsDocument,
  renderLeafDocsHTML,
} from '@emeryld/rrroutes-openapi'

// React element – mount into your own tree
const element = createLeafDocsDocument(registry.all, {
  assetBasePath: '/__rrroutes/docs/assets',
})

// Or prerender to a string
const html = renderLeafDocsHTML(registry.all, {
  assetBasePath: '/__rrroutes/docs/assets',
})

Data shape

The docs UI expects serialized leaves from @emeryld/rrroutes-contract. Each leaf includes:

• method, path, and cfg (summary, description, tags, docsGroup, stability, deprecated, docsMeta, feed)
• Optional Zod schemas for params/query/body/output; these are introspected into a serializable AST for schema tables.

Preset CSV format

Presets use packages/openapi/src/web/v2/utils/presetCsv.ts for import/export. That module expects the heading presetId,presetName,presetDescription,presetGroupId,presetTags,opStepNumber,opName,opDescription,opMethod,opPath,opEndpointId,opQueryJson,opExtraHeadersJson,opBodyJson and emits the same order when saving CSV, with tags stored as ;-separated values and JSON cells kept compact.

Build / develop

pnpm install
pnpm run dev    # Vite dev server for the UI (serves index.html)
pnpm run build  # Builds node bundle + types + web assets to dist/public

Published package contents:

• dist/index.{mjs,cjs,d.ts}: server helper + exports
• dist/public/assets/docs.{js,css}: the docs UI bundle served by mountRRRoutesDocs