@raystack/chronicle 0.7.3 → 0.8.0

package/src/lib/openapi.ts

@@ -120,12 +120,38 @@ function convertV2toV3(doc: OpenAPIV2.Document): OpenAPIV3.Document {
     v3Paths[pathStr] = v3PathItem
   }
 
+  const securitySchemes = convertV2SecurityDefs(resolved.securityDefinitions as Record<string, OpenAPIV2.SecuritySchemeObject> | undefined)
+
   return {
     openapi: '3.0.0',
     info: resolved.info as unknown as OpenAPIV3.InfoObject,
     paths: v3Paths,
     tags: (resolved.tags ?? []) as unknown as OpenAPIV3.TagObject[],
+    ...(resolved.externalDocs ? { externalDocs: resolved.externalDocs as unknown as OpenAPIV3.ExternalDocumentationObject } : {}),
+    ...(Object.keys(securitySchemes).length > 0 ? { components: { securitySchemes } } : {}),
+  }
+}
+
+function convertV2SecurityDefs(defs: Record<string, OpenAPIV2.SecuritySchemeObject> | undefined): Record<string, OpenAPIV3.SecuritySchemeObject> {
+  if (!defs) return {}
+  const result: Record<string, OpenAPIV3.SecuritySchemeObject> = {}
+  for (const [name, def] of Object.entries(defs)) {
+    if (def.type === 'apiKey') {
+      result[name] = { type: 'apiKey', name: (def as JsonObject).name as string, in: def.in as string } as OpenAPIV3.ApiKeySecurityScheme
+    } else if (def.type === 'basic') {
+      result[name] = { type: 'http', scheme: 'basic' } as OpenAPIV3.HttpSecurityScheme
+    } else if (def.type === 'oauth2') {
+      const v2 = def as unknown as { flow?: string; authorizationUrl?: string; tokenUrl?: string; scopes?: Record<string, string> }
+      const flow = { authorizationUrl: v2.authorizationUrl ?? '', tokenUrl: v2.tokenUrl ?? '', scopes: v2.scopes ?? {} }
+      const flows: OpenAPIV3.OAuth2SecurityScheme['flows'] = {}
+      if (v2.flow === 'implicit') flows.implicit = { authorizationUrl: flow.authorizationUrl, scopes: flow.scopes }
+      else if (v2.flow === 'password') flows.password = { tokenUrl: flow.tokenUrl, scopes: flow.scopes }
+      else if (v2.flow === 'application') flows.clientCredentials = { tokenUrl: flow.tokenUrl, scopes: flow.scopes }
+      else if (v2.flow === 'accessCode') flows.authorizationCode = { authorizationUrl: flow.authorizationUrl, tokenUrl: flow.tokenUrl, scopes: flow.scopes }
+      result[name] = { type: 'oauth2', flows } as OpenAPIV3.OAuth2SecurityScheme
+    }
   }
+  return result
 }
 
 function convertV2Operation(op: OpenAPIV2.OperationObject): OpenAPIV3.OperationObject {

package/src/lib/schema.ts

@@ -1,19 +1,56 @@
 import type { OpenAPIV3 } from 'openapi-types'
 
+const schemaFieldKinds = {
+  string: 'string', integer: 'integer', number: 'number',
+  boolean: 'boolean', array: 'array', object: 'object',
+} as const
+
+export type SchemaFieldKind = keyof typeof schemaFieldKinds
+
+export function toKind(type: unknown): SchemaFieldKind {
+  if (typeof type === 'string' && type in schemaFieldKinds) return type as SchemaFieldKind
+  return 'object'
+}
+
 export interface SchemaField {
   name: string
   type: string
+  kind: SchemaFieldKind
   required: boolean
   description?: string
   default?: unknown
+  example?: unknown
   enum?: unknown[]
   children?: SchemaField[]
 }
 
+function mergeAllOf(schema: OpenAPIV3.SchemaObject): OpenAPIV3.SchemaObject {
+  const composed = schema.allOf ?? schema.oneOf ?? schema.anyOf
+  if (!composed) return schema
+  const merged: OpenAPIV3.SchemaObject = { ...schema }
+  delete merged.allOf
+  delete merged.oneOf
+  delete merged.anyOf
+  for (const sub of composed as OpenAPIV3.SchemaObject[]) {
+    if (sub.type) merged.type = sub.type
+    if (sub.properties) {
+      merged.properties = { ...(merged.properties ?? {}), ...sub.properties }
+    }
+    if (sub.required) {
+      merged.required = [...(merged.required ?? []), ...sub.required]
+    }
+    if (sub.description && !merged.description) merged.description = sub.description
+  }
+  return merged
+}
+
 export function flattenSchema(
   schema: OpenAPIV3.SchemaObject,
   requiredFields: string[] = [],
 ): SchemaField[] {
+  const resolved = mergeAllOf(schema)
+  if (resolved !== schema) return flattenSchema(resolved, requiredFields)
+
   if (schema.type === 'array' && schema.items) {
     const items = schema.items as OpenAPIV3.SchemaObject
     const itemType = inferType(items)
@@ -26,6 +63,7 @@ export function flattenSchema(
     return [{
       name: 'items',
       type: `${itemType}[]`,
+      kind: 'array' as SchemaFieldKind,
       required: true,
       description: items.description,
       children: children?.length ? children : undefined,
@@ -36,7 +74,8 @@ export function flattenSchema(
     const properties = (schema.properties ?? {}) as Record<string, OpenAPIV3.SchemaObject>
     const required = schema.required ?? requiredFields
 
-    return Object.entries(properties).map(([name, prop]) => {
+    return Object.entries(properties).map(([name, rawProp]) => {
+      const prop = mergeAllOf(rawProp)
       const fieldType = inferType(prop)
       const children =
         fieldType === 'object' || prop.properties
@@ -48,9 +87,11 @@ export function flattenSchema(
       return {
         name,
         type: fieldType,
+        kind: toKind(prop.type),
         required: required.includes(name),
-        description: prop.description,
+        description: rawProp.description ?? prop.description,
         default: prop.default,
+        example: prop.example,
         enum: prop.enum,
         children: children?.length ? children : undefined,
       }
@@ -87,7 +128,8 @@ export function generateExampleJson(schema: OpenAPIV3.SchemaObject): unknown {
   return defaults[schema.type as string] ?? null
 }
 
-function inferType(schema: OpenAPIV3.SchemaObject): string {
+function inferType(rawSchema: OpenAPIV3.SchemaObject): string {
+  const schema = mergeAllOf(rawSchema)
   if (schema.type === 'array') {
     const items = schema.items as OpenAPIV3.SchemaObject | undefined
     const itemType = items ? inferType(items) : 'unknown'

package/src/lib/source.ts

@@ -97,6 +97,8 @@ function buildSyntheticMeta(): {
 }
 
 let cachedSource: ReturnType<typeof loader> | null = null;
+let cachedTree: Root | null = null;
+let cachedNavMap: Map<string, PageNav> | null = null;
 
 async function getSource() {
   if (cachedSource) return cachedSource;
@@ -112,42 +114,65 @@ export { getSource as source };
 
 export function invalidate() {
   cachedSource = null;
+  cachedTree = null;
+  cachedNavMap = null;
 }
 
-function getOrder(node: Node, orderMap: Map<string, number>): number | undefined {
-  if (node.type === 'page') return orderMap.get(node.url);
-  if (node.type === 'folder' && node.index) return orderMap.get(node.index.url);
+function getOrder(node: Node, pageOrderMap: Map<string, number>, folderOrderMap: Map<string, number>): number | undefined {
+  if (node.type === 'page') return pageOrderMap.get(node.url);
+  if (node.type === 'folder') {
+    if (node.index) {
+      const fromMeta = folderOrderMap.get(node.index.url);
+      if (fromMeta !== undefined) return fromMeta;
+      return pageOrderMap.get(node.index.url);
+    }
+  }
   return undefined;
 }
 
-function sortNodes(nodes: Node[], orderMap: Map<string, number>): Node[] {
+function sortNodes(nodes: Node[], pageOrderMap: Map<string, number>, folderOrderMap: Map<string, number>): Node[] {
   return [...nodes]
     .map(n =>
       n.type === 'folder'
-        ? ({ ...n, children: sortNodes(n.children, orderMap) } as Folder)
+        ? ({ ...n, children: sortNodes(n.children, pageOrderMap, folderOrderMap) } as Folder)
         : n
     )
     .sort(
       (a, b) =>
-        (getOrder(a, orderMap) ?? Number.MAX_SAFE_INTEGER) -
-        (getOrder(b, orderMap) ?? Number.MAX_SAFE_INTEGER)
+        (getOrder(a, pageOrderMap, folderOrderMap) ?? Number.MAX_SAFE_INTEGER) -
+        (getOrder(b, pageOrderMap, folderOrderMap) ?? Number.MAX_SAFE_INTEGER)
     );
 }
 
-function sortTreeByOrder(tree: Root, pages: { url: string; data: unknown }[]): Root {
-  const orderMap = new Map<string, number>();
+function buildFolderOrderMap(metaFiles: { path: string; data: Record<string, unknown> }[]): Map<string, number> {
+  const map = new Map<string, number>();
+  for (const meta of metaFiles) {
+    const order = meta.data.order as number | undefined;
+    if (order === undefined) continue;
+    const folderUrl = '/' + meta.path.replace(/\/meta\.json$/, '');
+    map.set(folderUrl, order);
+  }
+  return map;
+}
+
+function sortTreeByOrder(tree: Root, pages: { url: string; data: unknown }[], metaFiles: { path: string; data: Record<string, unknown> }[]): Root {
+  const pageOrderMap = new Map<string, number>();
   for (const page of pages) {
     const d = page.data as Record<string, unknown>;
     const order = d.order as number | undefined;
-    if (order !== undefined) orderMap.set(page.url, order);
-    if (page.url === '/') orderMap.set('/', order ?? 0);
+    if (order !== undefined) pageOrderMap.set(page.url, order);
+    if (page.url === '/') pageOrderMap.set('/', order ?? 0);
   }
-  return { ...tree, children: sortNodes(tree.children, orderMap) };
+  const folderOrderMap = buildFolderOrderMap(metaFiles);
+  return { ...tree, children: sortNodes(tree.children, pageOrderMap, folderOrderMap) };
 }
 
 export async function getPageTree(): Promise<Root> {
+  if (cachedTree) return cachedTree;
   const s = await getSource();
-  return sortTreeByOrder(s.pageTree as Root, s.getPages());
+  const metaFiles = buildFiles().filter(f => f.type === 'meta') as { path: string; data: Record<string, unknown> }[];
+  cachedTree = sortTreeByOrder(s.pageTree as Root, s.getPages(), metaFiles);
+  return cachedTree;
 }
 
 export async function getPages() {
@@ -186,12 +211,10 @@ function titleFromUrl(url: string): string {
     .join(' ');
 }
 
-export async function getPageNav(slug: string[], tree?: Root): Promise<PageNav> {
-  const resolvedTree = tree ?? (await getPageTree());
-  const pages = flattenTree(resolvedTree.children);
-  const url = slug.length === 0 ? '/' : `/${slug.join('/')}`;
-  const i = pages.findIndex(p => p.url === url);
-  if (i < 0) return { prev: null, next: null };
+async function getNavMap(): Promise<Map<string, PageNav>> {
+  if (cachedNavMap) return cachedNavMap;
+  const tree = await getPageTree();
+  const pages = flattenTree(tree.children);
   const toLink = (p: (typeof pages)[number]): PageNavLink => ({
     url: p.url,
     title:
@@ -199,10 +222,21 @@ export async function getPageNav(slug: string[], tree?: Root): Promise<PageNav>
         ? p.name
         : titleFromUrl(p.url)
   });
-  return {
-    prev: i > 0 ? toLink(pages[i - 1]) : null,
-    next: i < pages.length - 1 ? toLink(pages[i + 1]) : null
-  };
+  const navMap = new Map<string, PageNav>();
+  for (let i = 0; i < pages.length; i++) {
+    navMap.set(pages[i].url, {
+      prev: i > 0 ? toLink(pages[i - 1]) : null,
+      next: i < pages.length - 1 ? toLink(pages[i + 1]) : null
+    });
+  }
+  cachedNavMap = navMap;
+  return cachedNavMap;
+}
+
+export async function getPageNav(slug: string[]): Promise<PageNav> {
+  const navMap = await getNavMap();
+  const url = slug.length === 0 ? '/' : `/${slug.join('/')}`;
+  return navMap.get(url) ?? { prev: null, next: null };
 }
 
 export function extractFrontmatter(page: { data: unknown }, fallbackTitle?: string): Frontmatter {

package/src/lib/use-api-operation.ts

@@ -0,0 +1,15 @@
+import { useMemo } from 'react'
+import { useLocation } from 'react-router'
+import { findApiOperation, type ApiRouteMatch } from '@/lib/api-routes'
+import { usePageContext } from '@/lib/page-context'
+
+export function useApiOperation(): ApiRouteMatch | null {
+  const { apiSpecs } = usePageContext()
+  const { pathname } = useLocation()
+
+  return useMemo(() => {
+    const slug = pathname.replace(/^\/apis\//, '').split('/').filter(Boolean)
+    if (slug.length !== 2) return null
+    return findApiOperation(apiSpecs, slug)
+  }, [apiSpecs, pathname])
+}

package/src/pages/ApiLayout.module.css

@@ -14,6 +14,7 @@
 .content {
   height: 100%;
   overflow-y: auto;
+  padding-left: 0;
   padding-right: 0;
 }
 

package/src/pages/ApiPage.tsx

@@ -1,9 +1,8 @@
-import { Flex, Headline, Text } from '@raystack/apsara';
 import type { OpenAPIV3 } from 'openapi-types';
-import { EndpointPage } from '@/components/api';
-import { findApiOperation } from '@/lib/api-routes';
+import { Navigate } from 'react-router';
+import { ApiOverview } from '@/components/api';
+import { findApiOperation, getFirstApiUrl } from '@/lib/api-routes';
 import { Head } from '@/lib/head';
-import type { ApiSpec } from '@/lib/openapi';
 import { usePageContext } from '@/lib/page-context';
 
 interface ApiPageProps {
@@ -14,16 +13,9 @@ export function ApiPage({ slug }: ApiPageProps) {
   const { config, apiSpecs } = usePageContext();
 
   if (slug.length === 0) {
-    return (
-      <>
-        <Head
-          title='API Reference'
-          description={`API documentation for ${config.site.title}`}
-          config={config}
-        />
-        <ApiLanding specs={apiSpecs} />
-      </>
-    );
+    const firstUrl = getFirstApiUrl(apiSpecs);
+    if (firstUrl) return <Navigate to={firstUrl} replace />;
+    return null;
   }
 
   const match = findApiOperation(apiSpecs, slug);
@@ -36,7 +28,7 @@ export function ApiPage({ slug }: ApiPageProps) {
   return (
     <>
       <Head title={title} description={operation.description} config={config} />
-      <EndpointPage
+      <ApiOverview
         method={match.method}
         path={match.path}
         operation={match.operation}
@@ -48,26 +40,3 @@ export function ApiPage({ slug }: ApiPageProps) {
   );
 }
 
-function ApiLanding({ specs }: { specs: ApiSpec[] }) {
-  return (
-    <Flex
-      direction='column'
-      gap='large'
-      style={{ padding: 'var(--rs-space-7)' }}
-    >
-      <Headline size='medium' as='h1'>
-        API Reference
-      </Headline>
-      {specs.map(spec => (
-        <Flex key={spec.name} direction='column' gap='small'>
-          <Headline size='small' as='h2'>
-            {spec.name}
-          </Headline>
-          {spec.document.info.description && (
-            <Text size={3}>{spec.document.info.description}</Text>
-          )}
-        </Flex>
-      ))}
-    </Flex>
-  );
-}

package/src/pages/DocsPage.tsx

@@ -1,7 +1,32 @@
+import { Navigate } from 'react-router';
 import { Head } from '@/lib/head';
 import { usePageContext } from '@/lib/page-context';
 import { NotFound } from '@/pages/NotFound';
 import { getTheme } from '@/themes/registry';
+import type { Node } from 'fumadocs-core/page-tree';
+
+function getFirstPageUrl(nodes: Node[]): string | null {
+  for (const node of nodes) {
+    if (node.type === 'page') return node.url;
+    if (node.type === 'folder') {
+      const url = getFirstPageUrl(node.children);
+      if (url) return url;
+    }
+  }
+  return null;
+}
+
+function findFolderFirstPage(nodes: Node[], pathname: string): string | null {
+  for (const node of nodes) {
+    if (node.type === 'folder') {
+      const folderUrl = node.index?.url;
+      if (folderUrl === pathname) return getFirstPageUrl(node.children);
+      const found = findFolderFirstPage(node.children, pathname);
+      if (found) return found;
+    }
+  }
+  return null;
+}
 
 interface DocsPageProps {
   slug: string[];
@@ -10,7 +35,21 @@ interface DocsPageProps {
 export function DocsPage({ slug }: DocsPageProps) {
   const { config, tree, page, isLoading, errorStatus } = usePageContext();
 
-  if (errorStatus === 404) return <NotFound />;
+  if (errorStatus === 404) {
+    const pathname = `/${slug.join('/')}`;
+    const contentConfig = config.content?.find(c => c.dir === slug[0]);
+    const isContentRoot = slug.length === 1 && slug[0] === contentConfig?.dir;
+    if (contentConfig?.index_page) {
+      return <Navigate to={`/${contentConfig.dir}/${contentConfig.index_page}`} replace />;
+    }
+    if (isContentRoot) {
+      const firstUrl = getFirstPageUrl(tree.children);
+      if (firstUrl) return <Navigate to={firstUrl} replace />;
+    }
+    const folderFirstUrl = findFolderFirstPage(tree.children, pathname);
+    if (folderFirstUrl) return <Navigate to={folderFirstUrl} replace />;
+    return <NotFound />;
+  }
   if (errorStatus) return <NotFound />;
   const { Page, Skeleton } = getTheme(config.theme?.name);
 

package/src/server/api/apis-proxy.ts

@@ -51,10 +51,17 @@ export default defineHandler(async event => {
       ? await response.json()
       : await response.text();
 
+    const sensitiveHeaders = new Set(['set-cookie', 'authorization', 'proxy-authorization', 'cookie']);
+    const responseHeaders: Record<string, string> = {};
+    response.headers.forEach((v, k) => {
+      if (!sensitiveHeaders.has(k.toLowerCase())) responseHeaders[k] = v;
+    });
+
     return Response.json({
       status: response.status,
       statusText: response.statusText,
-      body: responseBody
+      body: responseBody,
+      headers: responseHeaders
     });
   } catch (error) {
     const message =

package/src/server/entry-server.tsx

@@ -19,7 +19,7 @@ import serverAssets from './entry-server?assets=ssr';
 export default {
   async fetch(req: Request) {
     const url = new URL(req.url);
-    const pathname = url.pathname;
+    const pathname = decodeURIComponent(url.pathname);
 
     const config = loadConfig();
     const route = resolveRoute(pathname, config);
@@ -45,7 +45,7 @@ export default {
       getPageTree(),
       route.type === RouteType.DocsPage ? getPage(route.slug) : Promise.resolve(null),
     ]);
-    const nav = page ? await getPageNav(pageSlug, tree) : { prev: null, next: null };
+    const nav = page ? await getPageNav(pageSlug) : { prev: null, next: null };
 
     const relativePath = page ? getRelativePath(page) : null;
     const originalPath = page ? getOriginalPath(page) : null;

package/src/server/routes/[...slug].md.ts

@@ -7,6 +7,7 @@ import { safePath } from '@/server/utils/safe-path';
 export default defineHandler(async event => {
   const pathname = event.path || event.req.url?.split('?')[0] || '';
   if (!pathname.endsWith('.md')) return;
+  if (pathname.startsWith('/apis/')) return;
 
   const stripped = pathname.replace(/\.md$/, '');
   const parts = stripped === '/index' || stripped === '/'

package/src/server/routes/apis/[...slug].md.ts

@@ -0,0 +1,181 @@
+import type { OpenAPIV3 } from 'openapi-types'
+import { defineHandler, HTTPError } from 'nitro'
+import { loadConfig } from '@/lib/config'
+import { loadApiSpecs } from '@/lib/openapi'
+import { findApiOperation } from '@/lib/api-routes'
+import { flattenSchema, generateExampleJson, type SchemaField } from '@/lib/schema'
+import { generateCurl } from '@/lib/snippet-generators'
+
+export default defineHandler(async event => {
+  const pathname = event.path || event.req.url?.split('?')[0] || ''
+  if (!pathname.endsWith('.md')) return
+
+  const stripped = pathname.replace(/\.md$/, '').replace(/^\/apis\//, '')
+  const slug = stripped.split('/').filter(Boolean)
+  if (slug.length < 2) {
+    throw new HTTPError({ status: 404, message: 'Not Found' })
+  }
+
+  const config = loadConfig()
+  const specs = await loadApiSpecs(config.api ?? [])
+  const match = findApiOperation(specs, slug)
+
+  if (!match) {
+    throw new HTTPError({ status: 404, message: 'Not Found' })
+  }
+
+  const md = generateApiMarkdown(match.method, match.path, match.operation, match.spec.server.url, match.spec.auth)
+  return new Response(md, { headers: { 'Content-Type': 'text/markdown; charset=utf-8' } })
+})
+
+function generateApiMarkdown(
+  method: string,
+  path: string,
+  operation: OpenAPIV3.OperationObject,
+  serverUrl: string,
+  auth?: { type: string; header: string; placeholder?: string },
+): string {
+  const lines: string[] = []
+  const params = (operation.parameters ?? []) as OpenAPIV3.ParameterObject[]
+
+  lines.push(`# ${operation.summary ?? `${method} ${path}`}`)
+  lines.push('')
+  if (operation.description) {
+    lines.push(operation.description)
+    lines.push('')
+  }
+  lines.push(`\`${method}\` \`${path}\``)
+  lines.push('')
+
+  const headerParams = params.filter(p => p.in === 'header')
+  const pathParams = params.filter(p => p.in === 'path')
+  const queryParams = params.filter(p => p.in === 'query')
+
+  if (auth || headerParams.length > 0) {
+    lines.push('## Authorization')
+    lines.push('')
+    lines.push('| Header | Type | Required | Description |')
+    lines.push('| --- | --- | --- | --- |')
+    if (auth) {
+      lines.push(`| \`${auth.header}\` | string | Yes | ${auth.placeholder ?? 'API key'} |`)
+    }
+    for (const p of headerParams) {
+      const schema = (p.schema ?? {}) as OpenAPIV3.SchemaObject
+      lines.push(`| \`${p.name}\` | ${schema.type ?? 'string'} | ${p.required ? 'Yes' : 'No'} | ${p.description ?? ''} |`)
+    }
+    lines.push('')
+  }
+
+  if (pathParams.length > 0) {
+    lines.push('## Path Parameters')
+    lines.push('')
+    lines.push('| Parameter | Type | Required | Description |')
+    lines.push('| --- | --- | --- | --- |')
+    for (const p of pathParams) {
+      const schema = (p.schema ?? {}) as OpenAPIV3.SchemaObject
+      lines.push(`| \`${p.name}\` | ${schema.type ?? 'string'} | ${p.required ? 'Yes' : 'No'} | ${p.description ?? ''} |`)
+    }
+    lines.push('')
+  }
+
+  if (queryParams.length > 0) {
+    lines.push('## Query Parameters')
+    lines.push('')
+    lines.push('| Parameter | Type | Required | Description |')
+    lines.push('| --- | --- | --- | --- |')
+    for (const p of queryParams) {
+      const schema = (p.schema ?? {}) as OpenAPIV3.SchemaObject
+      lines.push(`| \`${p.name}\` | ${schema.type ?? 'string'} | ${p.required ? 'Yes' : 'No'} | ${p.description ?? ''} |`)
+    }
+    lines.push('')
+  }
+
+  const requestBody = operation.requestBody as OpenAPIV3.RequestBodyObject | undefined
+  if (requestBody?.content) {
+    const contentType = Object.keys(requestBody.content)[0]
+    const schema = contentType ? requestBody.content[contentType]?.schema as OpenAPIV3.SchemaObject : undefined
+    if (schema) {
+      lines.push('## Request Body')
+      lines.push('')
+      lines.push(`Content-Type: \`${contentType}\``)
+      lines.push('')
+      const fields = flattenSchema(schema)
+      if (fields.length > 0) {
+        lines.push('| Field | Type | Required | Description |')
+        lines.push('| --- | --- | --- | --- |')
+        renderFieldTable(fields, lines, 0)
+        lines.push('')
+      }
+      const example = generateExampleJson(schema)
+      lines.push('**Example:**')
+      lines.push('')
+      lines.push('```json')
+      lines.push(JSON.stringify(example, null, 2))
+      lines.push('```')
+      lines.push('')
+    }
+  }
+
+  const responses = operation.responses as Record<string, OpenAPIV3.ResponseObject> | undefined
+  if (responses) {
+    lines.push('## Responses')
+    lines.push('')
+    for (const [status, resp] of Object.entries(responses)) {
+      lines.push(`### ${status}${resp.description ? ` — ${resp.description}` : ''}`)
+      lines.push('')
+      const content = resp.content ?? {}
+      const contentType = Object.keys(content)[0]
+      const schema = contentType ? content[contentType]?.schema as OpenAPIV3.SchemaObject : undefined
+      if (schema) {
+        const fields = flattenSchema(schema)
+        if (fields.length > 0) {
+          lines.push('| Field | Type | Description |')
+          lines.push('| --- | --- | --- |')
+          renderResponseFieldTable(fields, lines, 0)
+          lines.push('')
+        }
+        const example = generateExampleJson(schema)
+        lines.push('```json')
+        lines.push(JSON.stringify(example, null, 2))
+        lines.push('```')
+        lines.push('')
+      }
+    }
+  }
+
+  const headers: Record<string, string> = {}
+  if (auth) headers[auth.header] = auth.placeholder ?? 'YOUR_API_KEY'
+  if (requestBody?.content) {
+    const ct = Object.keys(requestBody.content)[0]
+    if (ct) headers['Content-Type'] = ct
+  }
+
+  const bodySchema = requestBody?.content
+    ? (Object.values(requestBody.content)[0]?.schema as OpenAPIV3.SchemaObject | undefined)
+    : undefined
+  const bodyStr = bodySchema ? JSON.stringify(generateExampleJson(bodySchema), null, 2) : undefined
+
+  lines.push('## cURL')
+  lines.push('')
+  lines.push('```bash')
+  lines.push(generateCurl({ method, url: serverUrl + path, headers, body: bodyStr }))
+  lines.push('```')
+
+  return lines.join('\n')
+}
+
+function renderFieldTable(fields: SchemaField[], lines: string[], depth: number) {
+  const indent = '  '.repeat(depth)
+  for (const f of fields) {
+    lines.push(`| ${indent}\`${f.name}\` | ${f.type} | ${f.required ? 'Yes' : 'No'} | ${f.description ?? ''} |`)
+    if (f.children) renderFieldTable(f.children, lines, depth + 1)
+  }
+}
+
+function renderResponseFieldTable(fields: SchemaField[], lines: string[], depth: number) {
+  const indent = '  '.repeat(depth)
+  for (const f of fields) {
+    lines.push(`| ${indent}\`${f.name}\` | ${f.type} | ${f.description ?? ''} |`)
+    if (f.children) renderResponseFieldTable(f.children, lines, depth + 1)
+  }
+}

package/src/server/vite-config.ts

@@ -48,6 +48,7 @@ export async function createViteConfig(
 
   return {
     root: packageRoot,
+    publicDir: path.resolve(projectRoot, 'public'),
     configFile: false,
     plugins: [
       nitro({
@@ -131,6 +132,7 @@ export async function createViteConfig(
     },
     nitro: {
       logLevel: 2,
+      publicAssets: [{ dir: path.resolve(projectRoot, 'public') }],
       output: {
         dir: resolveOutputDir(projectRoot, preset),
       },