vocs 2.0.17 → 2.1.2

package/src/internal/openapi/markdown.ts

@@ -0,0 +1,275 @@
+import type { Config } from '../config.js'
+import type { Ir, IrGroup, IrOperation, IrParameter, IrResponse } from './parser.js'
+import * as Registry from './registry.js'
+import { codeSamples } from './sample.js'
+import { unwrapSingleVariant } from './union.js'
+
+/**
+ * A generated Markdown page for an OpenAPI route, ready to be served verbatim by
+ * the `.md` router / written as an `/assets/md` asset.
+ */
+export type Page = {
+  path: string
+  title: string
+  description?: string | undefined
+  /** Final Markdown, used verbatim (no MDX reprocessing). */
+  content: string
+}
+
+/**
+ * Builds Markdown pages for every configured OpenAPI section.
+ *
+ * Produces one page per mount (the section overview, listing every category and
+ * its endpoints) plus one page per category (`${mount}/${group.id}`), rendering
+ * each operation's parameters, request body, responses, and an example request.
+ *
+ * These mirror the routes created in the Waku router so `/<mount>.md` and
+ * `/<mount>/<group>.md` resolve to a readable, agent-friendly version of the
+ * same reference shown in the browser.
+ */
+export async function toPages(config: Config): Promise<Page[]> {
+  if (!config.openapi?.length) return []
+
+  const specs = await Registry.build(config)
+  return Object.values(specs).flatMap(fromIr)
+}
+
+/**
+ * Builds the Markdown pages for a single parsed spec: the section overview plus
+ * one page per category. Pure (no registry/network), so it's the unit-testable
+ * seam under {@link toPages}.
+ */
+export function fromIr(ir: Ir): Page[] {
+  return [overviewPage(ir), ...ir.groups.map((group) => groupPage(ir, group))]
+}
+
+/** Section overview page: API metadata + every category's endpoints. */
+function overviewPage(ir: Ir): Page {
+  return {
+    path: ir.path,
+    title: ir.info.title,
+    description: ir.info.description ? oneLine(ir.info.description) : undefined,
+    content: renderOverview(ir, normalizeMount(ir.path)),
+  }
+}
+
+/**
+ * Markdown for the section overview: API metadata + every category's endpoints.
+ *
+ * `linkBase` is prepended to operation anchors so the endpoint links resolve to
+ * wherever the section is mounted (the site uses the configured spec path; the
+ * standalone handler passes the live host mount).
+ */
+export function renderOverview(ir: Ir, linkBase: string): string {
+  const base = normalizeMount(linkBase)
+  const lines: string[] = [`# ${ir.info.title}`, '']
+  if (ir.info.version) lines.push(`Version: \`${ir.info.version}\``, '')
+  if (ir.info.description) lines.push(ir.info.description.trim(), '')
+
+  if (ir.servers.length > 0) {
+    lines.push('## Servers', '')
+    for (const server of ir.servers)
+      lines.push(
+        `- \`${server.url}\`${server.description ? `: ${oneLine(server.description)}` : ''}`,
+      )
+    lines.push('')
+  }
+
+  lines.push('## Endpoints', '')
+  for (const group of ir.groups) {
+    lines.push(`### ${group.name}`, '')
+    if (group.description) lines.push(oneLine(group.description), '')
+    for (const operation of group.operations) {
+      const href = `${base}/${group.id}#${operation.id}`
+      const label = operation.summary ? `: ${oneLine(operation.summary)}` : ''
+      lines.push(`- [\`${operation.method} ${operation.path}\`](${href})${label}`)
+    }
+    lines.push('')
+  }
+
+  return `${lines.join('\n').trimEnd()}\n`
+}
+
+/** Category page: full detail for each operation in the group. */
+function groupPage(ir: Ir, group: IrGroup): Page {
+  return {
+    path: `${normalizeMount(ir.path)}/${group.id}`,
+    title: group.name,
+    description: group.description ? oneLine(group.description) : undefined,
+    content: renderGroup(ir, group),
+  }
+}
+
+/** Markdown for a single category: full detail for each of its operations. */
+export function renderGroup(ir: Ir, group: IrGroup): string {
+  const lines: string[] = [`# ${group.name}`, '']
+  if (group.description) lines.push(group.description.trim(), '')
+
+  const server = ir.servers[0]?.url
+  for (const operation of group.operations) lines.push(...operationLines(operation, server))
+
+  return `${lines.join('\n').trimEnd()}\n`
+}
+
+function operationLines(operation: IrOperation, server?: string): string[] {
+  const lines: string[] = []
+  const title = operation.summary ?? `${operation.method} ${operation.path}`
+  lines.push(`## ${title}`, '')
+  lines.push(`\`${operation.method} ${operation.path}\``, '')
+  if (operation.deprecated) lines.push('> **Deprecated**', '')
+  if (operation.description) lines.push(operation.description.trim(), '')
+
+  const byLocation = (location: IrParameter['in']) =>
+    operation.parameters.filter((parameter) => parameter.in === location && !parameter.deprecated)
+
+  for (const [location, heading] of [
+    ['path', 'Path parameters'],
+    ['query', 'Query parameters'],
+    ['header', 'Header parameters'],
+    ['rpc', 'Parameters'],
+  ] as const) {
+    const params = byLocation(location)
+    if (params.length === 0) continue
+    lines.push(`### ${heading}`, '')
+    for (const parameter of params) lines.push(...parameterLines(parameter))
+    lines.push('')
+  }
+
+  if (operation.requestBody && !operation.requestBody.hidden) {
+    const body = operation.requestBody
+    const media = body.content[0]
+    const mediaType = media ? ` (\`${media.mediaType}\`)` : ''
+    lines.push(`### Request body${body.required ? ' (required)' : ''}${mediaType}`, '')
+    if (body.description) lines.push(oneLine(body.description), '')
+    if (media?.schema) {
+      const props = schemaLines(media.schema, 0)
+      if (props.length > 0) lines.push(...props, '')
+    }
+  }
+
+  if (operation.responses.length > 0) {
+    lines.push('### Responses', '')
+    for (const response of operation.responses) lines.push(...responseLines(response))
+  }
+
+  const samples = codeSamples(operation, server)
+  if (samples.length > 0) {
+    lines.push('### Example request', '')
+    for (const sample of samples) {
+      lines.push(`\`\`\`${sample.lang}`, sample.code.trim(), '```', '')
+    }
+  }
+
+  return lines
+}
+
+function parameterLines(parameter: IrParameter): string[] {
+  // Unwrap a nullable single-variant union so an object param's member type and
+  // nested properties surface (e.g. an RPC `Transaction` object's fields).
+  const schema = parameter.schema
+    ? (unwrapSingleVariant(parameter.schema) ?? parameter.schema)
+    : parameter.schema
+  const required = parameter.required ? ' _(required)_' : ''
+  const type = `\`${typeLabel(schema)}\``
+  const description = parameter.description ? `: ${oneLine(parameter.description)}` : ''
+  return [`- \`${parameter.name}\` ${type}${required}${description}`, ...schemaLines(schema, 1)]
+}
+
+function responseLines(response: IrResponse): string[] {
+  const lines: string[] = []
+  const description = response.description ? `: ${oneLine(response.description)}` : ''
+  lines.push(`#### \`${response.status}\`${description}`, '')
+
+  if (response.headers.length > 0) {
+    lines.push('Headers:', '')
+    for (const header of response.headers)
+      lines.push(
+        `- \`${header.name}\` \`${typeLabel(header.schema)}\`${
+          header.description ? `: ${oneLine(header.description)}` : ''
+        }`,
+      )
+    lines.push('')
+  }
+
+  const media = response.content[0]
+  if (media?.schema) {
+    const props = schemaLines(media.schema, 0)
+    if (props.length > 0) {
+      if (media.mediaType) lines.push(`Body (\`${media.mediaType}\`):`, '')
+      lines.push(...props, '')
+    }
+  }
+
+  return lines
+}
+
+const maxDepth = 4
+
+/**
+ * Renders an object schema's properties as an indented Markdown bullet list,
+ * recursing into nested objects (and array-of-object items) up to {@link
+ * maxDepth}. Returns an empty array for non-object schemas.
+ */
+function schemaLines(rawSchema: SchemaObject | undefined, depth: number): string[] {
+  if (!rawSchema || depth > maxDepth) return []
+
+  // Unwrap a nullable single-variant union (e.g. `oneOf: [null, X]`) so the
+  // member's properties are listed instead of nothing.
+  const schema = unwrapSingleVariant(rawSchema) ?? rawSchema
+  const target = schema['type'] === 'array' ? (schema['items'] as SchemaObject) : schema
+  const properties = target?.['properties'] as Record<string, SchemaObject> | undefined
+  if (!properties) return []
+
+  const required = new Set((target?.['required'] as string[] | undefined) ?? [])
+  const indent = '  '.repeat(depth)
+  const lines: string[] = []
+
+  for (const [name, rawProperty] of Object.entries(properties)) {
+    const property = unwrapSingleVariant(rawProperty) ?? rawProperty
+    const requiredFlag = required.has(name) ? ' _(required)_' : ''
+    const description = property['description']
+      ? `: ${oneLine(String(property['description']))}`
+      : ''
+    lines.push(`${indent}- \`${name}\` \`${typeLabel(property)}\`${requiredFlag}${description}`)
+    lines.push(...schemaLines(property, depth + 1))
+  }
+
+  return lines
+}
+
+type SchemaObject = Record<string, unknown>
+
+/** Compact, human-readable type label for a JSON Schema (post-dereference). */
+function typeLabel(schema: SchemaObject | undefined): string {
+  if (!schema) return 'unknown'
+
+  if (Array.isArray(schema['type'])) return (schema['type'] as string[]).join(' | ')
+
+  const composite = (schema['oneOf'] ?? schema['anyOf']) as SchemaObject[] | undefined
+  if (composite) return [...new Set(composite.map(typeLabel))].join(' | ')
+
+  if (Array.isArray(schema['allOf']))
+    return (schema['allOf'] as SchemaObject[]).map(typeLabel).join(' & ')
+
+  if (schema['type'] === 'array') return `${typeLabel(schema['items'] as SchemaObject)}[]`
+
+  if (typeof schema['type'] === 'string') {
+    const format = schema['format'] ? ` <${schema['format']}>` : ''
+    return `${schema['type']}${format}`
+  }
+
+  if (Array.isArray(schema['enum'])) return 'enum'
+  if (schema['properties']) return 'object'
+
+  return 'unknown'
+}
+
+/** Collapse Markdown/whitespace to a single readable line (for summaries). */
+function oneLine(value: string): string {
+  return value.replace(/\s+/g, ' ').trim()
+}
+
+/** Mount path without a trailing slash (e.g. `/` -> ``, `/api/` -> `/api`). */
+function normalizeMount(path: string): string {
+  return path === '/' ? '' : path.replace(/\/$/, '')
+}

package/src/internal/openapi/openapi.ts

@@ -0,0 +1,212 @@
+/**
+ * OpenAPI integration config.
+ *
+ * Mounts an isolated, auto-generated API reference section in the docs from an
+ * OpenAPI spec. Use {@link from} to define an entry in `vocs.config.ts`.
+ */
+
+import type * as VocsConfig from '../config.js'
+import type { SidebarItem } from '../sidebar.js'
+
+/**
+ * Spec source.
+ *
+ * - A file path relative to the project root (e.g. `./openapi.yaml`).
+ * - A URL (e.g. `https://example.com/openapi.json`).
+ * - Raw JSON/YAML content.
+ * - An inline OpenAPI document object.
+ */
+export type Spec = string | Record<string, unknown>
+
+/**
+ * A spec source, an already-started promise resolving to one, or a (lazy)
+ * provider that returns one. Promises/providers are awaited once when the
+ * reference is first rendered (and the result reused), so specs generated at
+ * runtime — e.g. from a server framework like `hono-openapi` — can be passed
+ * without resolving them up front. This lets `Handler.openApi` be constructed
+ * synchronously (and mounted via `app.route(...)`) even when the spec is
+ * produced asynchronously: build it eagerly and pass the promise directly.
+ *
+ * @example
+ * ```ts
+ * const spec = generateSpecs(app) // Promise<Spec>, started eagerly
+ * app.route('/', Handler.openApi({ spec }, { fallback: 'next' }))
+ * ```
+ */
+export type SpecInput = Spec | Promise<Spec> | (() => Spec | Promise<Spec>)
+
+/**
+ * Extra sidebar items to add around the auto-generated section.
+ *
+ * These are typically links to consumer-authored override/guide pages mounted
+ * under the same `path` (e.g. `pages/api/auth.mdx`).
+ */
+export type SidebarExtras = {
+  /** Items prepended above the generated `Introduction`/categories. */
+  top?: SidebarItem[] | undefined
+  /** Items appended below the generated categories. */
+  bottom?: SidebarItem[] | undefined
+  /**
+   * Items nested under the generated `Introduction` entry. When provided, the
+   * `Introduction` leaf becomes a collapsible group whose first child is an
+   * `Overview` link to the landing page, followed by these items (typically
+   * links to guide `pages` mounted under the section, e.g. authentication or
+   * versioning).
+   */
+  intro?: SidebarItem[] | undefined
+  /**
+   * Collapse the generated category groups by default. The group matching the
+   * active page still auto-expands, so deep links stay navigable. The generated
+   * `Introduction` entry is unaffected.
+   *
+   * @default false
+   */
+  collapsed?: boolean | undefined
+}
+
+/**
+ * A consumer-authored `.md`/`.mdx` page mounted into an OpenAPI section.
+ *
+ * In the Vite/site integration these are discovered automatically by the file
+ * router (e.g. `pages/api/auth.mdx`). In the standalone server handler
+ * ({@link file://./../../server/handlers.ts `Handler.openApi`}) — which has no
+ * filesystem router — they are supplied explicitly so override/guide content can
+ * still be rendered.
+ *
+ * - `path` is the route relative to the section mount (e.g. `/` overrides the
+ *   landing intro, `/auth` is a guide page, `/<group>` overrides a category
+ *   header).
+ * - `file` is the path to the `.md`/`.mdx` source, resolved against the handler
+ *   `rootDir` (default `process.cwd()`). Reading a file requires `node:fs`, so
+ *   on filesystem-less runtimes (e.g. Cloudflare Workers) supply `content`
+ *   instead.
+ * - `content` is the `.md`/`.mdx` source inline, an alternative to `file` that
+ *   needs no filesystem access. Exactly one of `file`/`content` is required.
+ * - `title` overrides the document title otherwise taken from frontmatter or the
+ *   first `# heading`, and renders as the page's heading on standalone guide
+ *   pages.
+ * - `description` renders as a subtitle below the title on standalone guide
+ *   pages (Markdown). Also taken from frontmatter `description` when omitted.
+ */
+export type Page = {
+  path: string
+  file?: string | undefined
+  content?: string | undefined
+  title?: string | undefined
+  description?: string | undefined
+}
+
+export type Config = {
+  /**
+   * OpenAPI spec source: file path, URL, raw content, inline object, or a (lazy)
+   * provider function returning any of those.
+   */
+  spec: SpecInput
+  /**
+   * Mount path for the generated API reference section.
+   *
+   * The section gets its own isolated sidebar scoped to this path.
+   *
+   * Required for the Vite/site integration. Optional for the standalone
+   * {@link file://./../../server/handlers.ts `Handler.openApi`} handler (the
+   * Hono mount provides the location; `path` only seeds generated link bases and
+   * defaults to `/`).
+   *
+   * @example "/api"
+   */
+  path?: string | undefined
+  /**
+   * Extra sidebar items to add around the auto-generated section (e.g. links to
+   * consumer-authored guide pages mounted under `path`).
+   *
+   * @example
+   * ```ts
+   * sidebar: {
+   *   top: [{ text: 'Authentication', link: '/api/auth' }],
+   *   bottom: [{ text: 'Errors', link: '/api/errors' }],
+   * }
+   * ```
+   */
+  sidebar?: SidebarExtras | undefined
+  /**
+   * Consumer-authored `.md`/`.mdx` override/guide pages.
+   *
+   * Only used by the standalone {@link file://./../../server/handlers.ts
+   * `Handler.openApi`} handler — the Vite/site integration discovers these via
+   * the file router instead.
+   */
+  pages?: Page[] | undefined
+  /**
+   * Vocs config passthrough for the standalone {@link
+   * file://./../../server/handlers.ts `Handler.openApi`} handler.
+   *
+   * The handler renders the real Vocs layout, so these options customize the
+   * chrome (theme, top navigation, logo, socials, …) exactly like a
+   * `vocs.config.ts`.
+   *
+   * `title` and `description` default to the spec's `info.title`/`info.description`
+   * but can be overridden here. `sidebar` is derived from the generated section
+   * (plus the `sidebar` config above) and cannot be set here.
+   *
+   * @example
+   * ```ts
+   * vocs: {
+   *   title: 'Acme Docs',
+   *   logoUrl: '/logo.svg',
+   *   theme: { accentColor: '#7c3aed' },
+   *   topNav: [{ text: 'Home', link: 'https://acme.com' }],
+   * }
+   * ```
+   */
+  vocs?: Omit<VocsConfig.define.Options, 'sidebar' | 'openapi'> | undefined
+}
+
+/**
+ * Config for the Vite/site integration, where `path` is required (it scopes the
+ * generated sidebar and routes).
+ */
+export type SiteConfig = Config & {
+  path: string
+}
+
+/**
+ * Defines an OpenAPI integration entry.
+ *
+ * @example
+ * ```ts
+ * import { OpenApi } from 'vocs/config'
+ *
+ * export default defineConfig({
+ *   openapi: [
+ *     OpenApi.from({ spec: './openapi.yaml', path: '/api' }),
+ *   ],
+ * })
+ * ```
+ */
+export function from(config: from.Options): SiteConfig {
+  const { spec, path, sidebar, pages } = config
+
+  if (!spec) throw new Error('[vocs] `openapi` entry is missing a `spec`.')
+  if (!path) throw new Error('[vocs] `openapi` entry is missing a `path`.')
+
+  return {
+    spec,
+    path: normalizePath(path),
+    ...(sidebar ? { sidebar } : {}),
+    ...(pages ? { pages } : {}),
+  }
+}
+
+export declare namespace from {
+  type Options = SiteConfig
+}
+
+/**
+ * Normalizes a mount path: ensures a leading slash and strips any trailing
+ * slash (except for the root `/`).
+ */
+export function normalizePath(path: string): string {
+  let normalized = path.startsWith('/') ? path : `/${path}`
+  if (normalized.length > 1 && normalized.endsWith('/')) normalized = normalized.slice(0, -1)
+  return normalized
+}