fumadocs-openapi 10.10.3 → 11.0.0

package/dist/ui/operation/request-tabs.js

@@ -1,67 +1,80 @@
-import { resolveRequestData } from "../../utils/url.js";
-import { I18nLabel } from "../client/i18n.js";
+"use client";
+import { useRenderContext } from "../contexts/api.js";
+import { ClientCodeBlock } from "../components/codeblock.js";
+import { pathnameFromRequest } from "../../requests/generators/index.js";
 import { MethodLabel } from "../components/method-label.js";
-import { AccordionContent, AccordionHeader, AccordionItem, AccordionTrigger, Accordions } from "../components/accordion.js";
+import { Markdown } from "../components/markdown.js";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import { useTranslations } from "@fuma-translate/react";
+import { AccordionContent, AccordionHeader, AccordionItem, AccordionTrigger, Accordions } from "@fumadocs/api-docs/components/accordion";
 import { Tabs, TabsContent, TabsList, TabsTrigger } from "fumadocs-ui/components/tabs";
 //#region src/ui/operation/request-tabs.tsx
-function RequestTabs({ path, operation, examples, ctx }) {
+function RequestTabs({ path, operation, method, pathItem, examples }) {
+	const ctx = useRenderContext();
 	if (!operation.requestBody) return null;
 	const { renderRequestTabs = renderRequestTabsDefault } = ctx.content ?? {};
-	return renderRequestTabs(examples, {
-		...ctx,
+	return renderRequestTabs({
+		items: examples,
 		route: path,
+		method,
+		pathItem,
 		operation
-	});
+	}, ctx);
+}
+function renderRequestTabsDefault(options) {
+	return /* @__PURE__ */ jsx(RequestTabsDefaultContent, { options });
 }
-function renderRequestTabsDefault(items, ctx) {
+function RequestTabsDefaultContent({ options }) {
+	const t = useTranslations({ note: "operation page" });
+	const { items } = options;
 	let children;
 	if (items.length > 1) children = /* @__PURE__ */ jsxs(Tabs, {
 		defaultValue: items[0].id,
 		children: [/* @__PURE__ */ jsx(TabsList, { children: items.map((item) => /* @__PURE__ */ jsx(TabsTrigger, {
 			value: item.id,
-			children: item.id === "_default" ? /* @__PURE__ */ jsx(I18nLabel, { label: "requestTabNameDefault" }) : item.name
+			children: item.id === "_default" ? t("Default") : item.name
 		}, item.id)) }), items.map((item) => /* @__PURE__ */ jsx(TabsContent, {
 			value: item.id,
 			children: /* @__PURE__ */ jsx(RequestTabsItem, {
 				item,
-				ctx
+				options
 			})
 		}, item.id))]
 	});
 	else if (items.length === 1) children = /* @__PURE__ */ jsx(RequestTabsItem, {
 		item: items[0],
-		ctx
+		options
 	});
 	else children = /* @__PURE__ */ jsx("p", {
 		className: "text-fd-muted-foreground text-xs",
-		children: /* @__PURE__ */ jsx(I18nLabel, { label: "empty" })
+		children: t("Empty")
 	});
 	return /* @__PURE__ */ jsxs("div", {
 		className: "p-3 rounded-xl border prose-no-margin bg-fd-card text-fd-card-foreground shadow-md",
 		children: [/* @__PURE__ */ jsx("p", {
 			className: "font-semibold border-b pb-2",
-			children: /* @__PURE__ */ jsx(I18nLabel, { label: "titleRequestTabs" })
+			children: t("Example Requests")
 		}), children]
 	});
 }
-function RequestTabsItem({ item, ctx }) {
+function RequestTabsItem({ item, options }) {
+	const t = useTranslations({ note: "operation page" });
 	const requestData = item.data;
 	const displayNames = {
-		body: /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsx(I18nLabel, { label: "titleRequestBody" }), /* @__PURE__ */ jsx("code", {
+		body: /* @__PURE__ */ jsxs(Fragment, { children: [t("Request Body"), /* @__PURE__ */ jsx("code", {
 			className: "text-xs text-fd-muted-foreground ms-auto",
 			children: requestData.bodyMediaType
 		})] }),
-		cookie: /* @__PURE__ */ jsx(I18nLabel, { label: "cookieParameters" }),
-		header: /* @__PURE__ */ jsx(I18nLabel, { label: "headerParameters" }),
-		query: /* @__PURE__ */ jsx(I18nLabel, { label: "queryParameters" }),
-		path: /* @__PURE__ */ jsx(I18nLabel, { label: "pathParameters" })
+		cookie: t("Cookie Parameters"),
+		header: t("Header Parameters"),
+		query: t("Query Parameters"),
+		path: t("Path Parameters")
 	};
 	return /* @__PURE__ */ jsxs(Fragment, { children: [
-		item.description && ctx.renderMarkdown(item.description),
+		item.description && /* @__PURE__ */ jsx(Markdown, { md: item.description }),
 		/* @__PURE__ */ jsxs("div", {
 			className: "flex flex-row gap-2 items-center justify-between",
-			children: [/* @__PURE__ */ jsx(MethodLabel, { children: requestData.method }), /* @__PURE__ */ jsx("code", { children: resolveRequestData(ctx.route, item.encoded) })]
+			children: [/* @__PURE__ */ jsx(MethodLabel, { children: requestData.method }), /* @__PURE__ */ jsx("code", { children: pathnameFromRequest(options.route, item.encoded) })]
 		}),
 		/* @__PURE__ */ jsx(Accordions, {
 			type: "multiple",
@@ -73,7 +86,7 @@ function RequestTabsItem({ item, ctx }) {
 					value: k,
 					children: [/* @__PURE__ */ jsx(AccordionHeader, { children: /* @__PURE__ */ jsx(AccordionTrigger, { children: v }) }), /* @__PURE__ */ jsx(AccordionContent, {
 						className: "prose-no-margin",
-						children: ctx.renderCodeBlock({
+						children: /* @__PURE__ */ jsx(ClientCodeBlock, {
 							lang: "json",
 							code: JSON.stringify(data, null, 2)
 						})

package/dist/ui/operation/response-tabs.d.ts

@@ -1,6 +1,6 @@
 import { ResponseObject } from "../../types.js";
-import { NoReference } from "../../utils/schema/index.js";
 import { ReactNode } from "react";
+import { NoReference } from "@fumadocs/api-docs/schema";
 
 //#region src/ui/operation/response-tabs.d.ts
 interface ResponseTab {
@@ -26,5 +26,8 @@ interface ResponseExample {
    */
   description?: string;
 }
+interface ResponseTabsRenderOptions {
+  tabs: ResponseTab[];
+}
 //#endregion
-export { ResponseTab };
+export { ResponseTabsRenderOptions };

package/dist/ui/operation/response-tabs.js

@@ -1,12 +1,18 @@
-import { getPreferredType } from "../../utils/schema/index.js";
-import { I18nLabel } from "../client/i18n.js";
-import { sample } from "../../utils/schema/sample.js";
-import { AccordionContent, AccordionHeader, AccordionItem, AccordionTrigger, Accordions } from "../components/accordion.js";
+"use client";
+import { getPreferredType } from "../../utils/schema.js";
+import { useRenderContext } from "../contexts/api.js";
+import { ClientCodeBlock } from "../components/codeblock.js";
+import { Markdown } from "../components/markdown.js";
 import { useMemo } from "react";
 import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
+import { useTranslations } from "@fuma-translate/react";
+import { AccordionContent, AccordionHeader, AccordionItem, AccordionTrigger, Accordions } from "@fumadocs/api-docs/components/accordion";
 import { Tab, Tabs } from "fumadocs-ui/components/tabs";
+import { sample } from "@fumadocs/api-docs/schema/sample";
 //#region src/ui/operation/response-tabs.tsx
-function ResponseTabs({ operation, ctx }) {
+function ResponseTabs({ operation }) {
+	const ctx = useRenderContext();
+	const t = useTranslations({ note: "operation page" });
 	const tabs = useMemo(() => {
 		const tabs = [];
 		if (!operation.responses) return tabs;
@@ -21,31 +27,32 @@ function ResponseTabs({ operation, ctx }) {
 			if (responseOfType?.examples) {
 				tab.examples ??= [];
 				for (const [key, sample] of Object.entries(responseOfType.examples)) tab.examples.push({
-					label: sample?.summary ?? /* @__PURE__ */ jsx(I18nLabel, {
-						label: "responseTabName",
-						replacements: { key }
-					}),
+					label: sample?.summary ?? t("Example {key}", { variables: { key } }),
 					sample: sample.value,
 					description: sample?.description
 				});
 			} else if (responseOfType?.example || responseOfType?.schema) {
 				tab.examples ??= [];
 				tab.examples.push({
-					label: /* @__PURE__ */ jsx(I18nLabel, { label: "responseTabNameDefault" }),
+					label: t("Example"),
 					sample: responseOfType.example ?? sample(responseOfType.schema)
 				});
 			}
 			tabs.push(tab);
 		}
 		return tabs;
-	}, [operation.responses]);
+	}, [operation.responses, t]);
 	if (tabs.length === 0) return null;
 	const { renderResponseTabs = renderResponseTabsDefault } = ctx.content ?? {};
-	return renderResponseTabs(tabs, ctx);
+	return renderResponseTabs({ tabs }, ctx);
 }
-function renderResponseTabsDefault(tabs, ctx) {
+function renderResponseTabsDefault({ tabs }) {
+	return /* @__PURE__ */ jsx(ResponseTabsDefaultContent, { tabs });
+}
+function ResponseTabsDefaultContent({ tabs }) {
+	const t = useTranslations({ note: "operation page" });
 	function renderExampleContent(example) {
-		return /* @__PURE__ */ jsxs(Fragment$1, { children: [example.description && ctx.renderMarkdown(example.description), ctx.renderCodeBlock({
+		return /* @__PURE__ */ jsxs(Fragment$1, { children: [example.description && /* @__PURE__ */ jsx(Markdown, { md: example.description }), /* @__PURE__ */ jsx(ClientCodeBlock, {
 			lang: "json",
 			code: JSON.stringify(example.sample, null, 2)
 		})] });
@@ -55,7 +62,7 @@ function renderResponseTabsDefault(tabs, ctx) {
 		items: tabs.map((tab) => tab.code),
 		children: tabs.map((tab) => {
 			const { examples = [] } = tab;
-			let slot = /* @__PURE__ */ jsx(I18nLabel, { label: "empty" });
+			let slot = t("Empty");
 			if (examples.length > 1) slot = /* @__PURE__ */ jsx(Accordions, {
 				type: "single",
 				className: "pt-2",

package/dist/ui/operation/usage-tabs.js

@@ -0,0 +1,144 @@
+"use client";
+import { useRenderContext, useServerContext } from "../contexts/api.js";
+import { ClientCodeBlock } from "../components/codeblock.js";
+import { createCodeUsageGeneratorRegistry, pathnameFromRequest } from "../../requests/generators/index.js";
+import { useOperationContext } from "./context.js";
+import { ResponseTabs } from "./response-tabs.js";
+import { useEffect, useMemo, useState } from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from "@fumadocs/api-docs/components/select";
+import { joinURL, resolveServerUrl } from "@fumadocs/api-docs/utils/url";
+import { CodeBlockTab, CodeBlockTabs, CodeBlockTabsList, CodeBlockTabsTrigger } from "fumadocs-ui/components/codeblock";
+//#region src/ui/operation/usage-tabs.tsx
+function UsageTabs({ method, operation, pathItem }) {
+	const ctx = useRenderContext();
+	let { renderAPIExampleUsageTabs, renderAPIExampleLayout } = ctx.content ?? {};
+	renderAPIExampleLayout ??= (slots) => {
+		return /* @__PURE__ */ jsxs("div", {
+			className: "prose-no-margin",
+			children: [
+				slots.selector,
+				slots.usageTabs,
+				slots.responseTabs
+			]
+		});
+	};
+	renderAPIExampleUsageTabs ??= (registry) => {
+		const map = Array.from(registry.map().entries());
+		if (map.length === 0) return null;
+		return /* @__PURE__ */ jsxs(CodeBlockTabs, {
+			groupId: "fumadocs_openapi_requests",
+			defaultValue: map[0][0],
+			children: [/* @__PURE__ */ jsx(CodeBlockTabsList, { children: map.map(([id, item]) => /* @__PURE__ */ jsx(CodeBlockTabsTrigger, {
+				value: id,
+				children: item.label ?? item.lang
+			}, id)) }), map.map(([id, item]) => /* @__PURE__ */ jsx(CodeBlockTab, {
+				value: id,
+				children: /* @__PURE__ */ jsx(UsageTab, {
+					id,
+					lang: item.lang
+				})
+			}, id))]
+		});
+	};
+	const registry = useMemo(() => {
+		const registry = createCodeUsageGeneratorRegistry(ctx.codeUsages);
+		if (ctx.generateCodeSamples) for (const gen of ctx.generateCodeSamples({
+			operation,
+			method,
+			pathItem
+		})) registry.addInline(gen);
+		if (operation["x-codeSamples"]) for (const sample of operation["x-codeSamples"]) registry.addInline(sample);
+		return registry;
+	}, [
+		ctx,
+		operation,
+		method,
+		pathItem
+	]);
+	return renderAPIExampleLayout({
+		selector: operation["x-exclusiveCodeSample"] ? null : /* @__PURE__ */ jsx(UsageTabsSelector, {}),
+		usageTabs: renderAPIExampleUsageTabs(registry, ctx),
+		responseTabs: /* @__PURE__ */ jsx(ResponseTabs, {
+			operation,
+			method,
+			pathItem
+		})
+	}, ctx);
+}
+function UsageTabsSelector() {
+	const { example: key, setExample: setKey, examples } = useOperationContext();
+	const { APIExampleSelector: Override } = useRenderContext().operation ?? {};
+	if (Override) return /* @__PURE__ */ jsx(Override, {
+		items: examples,
+		value: key,
+		onValueChange: setKey
+	});
+	function renderItem(item) {
+		return /* @__PURE__ */ jsxs("div", { children: [/* @__PURE__ */ jsx("span", {
+			className: "font-medium text-sm",
+			children: item.name
+		}), /* @__PURE__ */ jsx("span", {
+			className: "text-fd-muted-foreground",
+			children: item.description
+		})] });
+	}
+	if (examples.length === 1) return null;
+	const selected = examples.find((item) => item.id === key);
+	return /* @__PURE__ */ jsxs(Select, {
+		value: key,
+		onValueChange: setKey,
+		children: [/* @__PURE__ */ jsx(SelectTrigger, {
+			className: "not-prose mb-2",
+			children: selected && /* @__PURE__ */ jsx(SelectValue, {
+				asChild: true,
+				children: renderItem(selected)
+			})
+		}), /* @__PURE__ */ jsx(SelectContent, { children: examples.map((item) => /* @__PURE__ */ jsx(SelectItem, {
+			value: item.id,
+			children: renderItem(item)
+		}, item.id)) })]
+	});
+}
+function UsageTab({ id, lang }) {
+	const { mediaAdapters, codeUsages } = useRenderContext();
+	const { examples, example: selectedExampleId, route, addListener, removeListener } = useOperationContext();
+	const { server } = useServerContext();
+	const codegen = codeUsages.get(id);
+	const [mounted, setMounted] = useState(false);
+	const [data, setData] = useState(() => examples.find((example) => example.id === selectedExampleId)?.encoded);
+	useEffect(() => {
+		const listener = (_, encoded) => setData(encoded);
+		addListener(listener);
+		setMounted(true);
+		return () => {
+			removeListener(listener);
+		};
+	}, [addListener, removeListener]);
+	const code = useMemo(() => {
+		if (!data) return;
+		const url = joinURL(server && mounted ? new URL(resolveServerUrl(server.url, server.variables), window.location.origin).href : "https://example.com", pathnameFromRequest(route, data));
+		if (!codegen) return;
+		return codegen.generate({
+			...data,
+			url
+		}, {
+			mediaAdapters,
+			custom: null
+		});
+	}, [
+		data,
+		server,
+		route,
+		mounted,
+		codegen,
+		mediaAdapters
+	]);
+	if (!code) return null;
+	return /* @__PURE__ */ jsx(ClientCodeBlock, {
+		lang,
+		code
+	});
+}
+//#endregion
+export { UsageTabs };

package/dist/utils/document/dereference.d.ts

@@ -1,5 +1,5 @@
 import { Document } from "../../types.js";
-import { NoReference } from "../schema/index.js";
+import { NoReference } from "@fumadocs/api-docs/schema";
 
 //#region src/utils/document/dereference.d.ts
 interface DereferencedDocument {

package/dist/utils/document/dereference.js

@@ -1,19 +1,16 @@
-import { dereferenceSync } from "../schema/dereference.js";
+import { dereferenceSync } from "@fumadocs/api-docs/schema/dereference";
 //#region src/utils/document/dereference.ts
-function dereferenceDocument(bundled) {
-	/**
-	* Dereferenced value and its original `$ref` value
-	*/
+function dereferenceBundledDocument(bundled) {
 	const dereferenceMap = /* @__PURE__ */ new Map();
 	return {
 		bundled,
-		dereferenced: dereferenceSync(bundled, (schema, ref) => {
+		dereferenced: dereferenceSync(bundled, { setOriginalRef(schema, ref) {
 			dereferenceMap.set(schema, ref);
-		}),
+		} }),
 		getRawRef(obj) {
 			return dereferenceMap.get(obj);
 		}
 	};
 }
 //#endregion
-export { dereferenceDocument };
+export { dereferenceBundledDocument };

package/dist/utils/document/load.js

@@ -0,0 +1,17 @@
+import { upgrade } from "../../node_modules/.pnpm/@scalar_openapi-upgrader@0.2.9/node_modules/@scalar/openapi-upgrader/dist/upgrade.js";
+import { bundle } from "@fumadocs/api-docs/schema/bundle";
+//#region src/utils/document/load.ts
+/**
+* Process input document to a Fumadocs OpenAPI compatible format
+*/
+async function loadDocument(input) {
+	try {
+		let bundled = await bundle(input);
+		bundled = upgrade(bundled, "3.2");
+		return { bundled };
+	} catch (e) {
+		throw new Error(`[OpenAPI] Failed to resolve input: ${input}`, { cause: e });
+	}
+}
+//#endregion
+export { loadDocument };

package/dist/utils/get-example-requests.d.ts

@@ -0,0 +1,13 @@
+import { RawRequestData, RequestData } from "../requests/types.js";
+import { NoReference } from "@fumadocs/api-docs/schema";
+
+//#region src/utils/get-example-requests.d.ts
+interface ExampleRequestItem {
+  id: string;
+  name: string;
+  description?: string;
+  data: RawRequestData;
+  encoded: RequestData;
+}
+//#endregion
+export { ExampleRequestItem };

package/dist/{ui/operation → utils}/get-example-requests.js

@@ -1,50 +1,62 @@
-import { getPreferredType, pickExample } from "../../utils/schema/index.js";
-import { encodeRequestData } from "../../requests/media/encode.js";
-import { sample } from "../../utils/schema/sample.js";
-//#region src/ui/operation/get-example-requests.ts
-function getExampleRequests(path, operation, ctx) {
+import { getPreferredType, pickExample } from "./schema.js";
+import { encodeRequestData } from "../requests/media/encode.js";
+import { sample } from "@fumadocs/api-docs/schema/sample";
+//#region src/utils/get-example-requests.ts
+function getExampleRequests({ path, method, ctx, operation, pathItem }) {
 	const requestBody = operation.requestBody;
 	const media = requestBody?.content ? getPreferredType(requestBody.content) : null;
 	const bodyOfType = media ? requestBody.content[media] : null;
+	const parameters = [...operation.parameters ?? [], ...pathItem.parameters ?? []];
 	if (bodyOfType?.examples) {
 		const result = [];
 		for (const [key, value] of Object.entries(bodyOfType.examples)) {
-			const data = getRequestData(path, operation, key, ctx);
+			const data = getRequestData({
+				path,
+				body: operation.requestBody,
+				parameters,
+				sampleKey: key,
+				method
+			});
 			result.push({
 				id: key,
 				name: value.summary || key,
 				description: value.description,
 				data,
-				encoded: encodeRequestData(data, ctx.mediaAdapters, operation.parameters ?? [])
+				encoded: encodeRequestData(data, ctx.mediaAdapters, parameters)
 			});
 		}
 		if (result.length > 0) return result;
 	}
-	const data = getRequestData(path, operation, null, ctx);
+	const data = getRequestData({
+		path,
+		body: operation.requestBody,
+		method,
+		parameters
+	});
 	return [{
 		id: "_default",
 		name: "Default",
 		description: typeof bodyOfType?.schema === "object" ? bodyOfType.schema.description : void 0,
 		data,
-		encoded: encodeRequestData(data, ctx.mediaAdapters, operation.parameters ?? [])
+		encoded: encodeRequestData(data, ctx.mediaAdapters, parameters)
 	}];
 }
-function getRequestData(path, method, sampleKey, _ctx) {
+function getRequestData({ method, path, parameters, sampleKey, body }) {
 	const result = {
 		path: {},
 		cookie: {},
 		header: {},
 		query: {},
-		method: method.method
+		method
 	};
-	for (const param of method.parameters ?? []) {
+	for (const param of parameters) {
 		let value = pickExample(param);
 		if (value === void 0 && param.required) {
 			if (param.schema) value = sample(param.schema);
 			else if (param.content) {
 				const type = getPreferredType(param.content);
 				const content = type ? param.content[type] : void 0;
-				if (!content || !content.schema) throw new Error(`Cannot find "${param.name}" parameter info for media type "${type}" in ${path} ${method.method}`);
+				if (!content || !content.schema) throw new Error(`Cannot find "${param.name}" parameter info for media type "${type}" in ${path} ${method}`);
 				value = sample(content.schema);
 			}
 		}
@@ -61,17 +73,16 @@ function getRequestData(path, method, sampleKey, _ctx) {
 			default: result.path[param.name] = value;
 		}
 	}
-	if (method.requestBody?.content) {
-		const body = method.requestBody.content;
-		const type = getPreferredType(body);
-		if (!type) throw new Error(`Cannot find body schema for ${path} ${method.method}: missing media type`);
+	if (body?.content) {
+		const type = getPreferredType(body.content);
+		if (!type) throw new Error(`Cannot find body schema for ${path} ${method}: missing media type`);
 		result.bodyMediaType = type;
-		const bodyOfType = body[type];
+		const bodyOfType = body.content[type];
 		if (bodyOfType.examples && sampleKey) result.body = bodyOfType.examples[sampleKey].value;
 		else if (bodyOfType.example) result.body = bodyOfType.example;
 		else result.body = sample(bodyOfType?.schema ?? {}, {
-			skipReadOnly: method.method !== "get",
-			skipWriteOnly: method.method === "get",
+			skipReadOnly: method !== "get",
+			skipWriteOnly: method === "get",
 			skipNonRequired: true
 		});
 	}

package/dist/utils/pages/builder.d.ts

@@ -1,7 +1,5 @@
-import { OperationItem, WebhookItem } from "../../ui/api-page.js";
-import { OperationObject, PathItemObject, TagObject } from "../../types.js";
-import { NoReference } from "../schema/index.js";
-import { DereferencedDocument } from "../document/dereference.js";
+import { Document, HttpMethods, OperationObject, PathItemObject, TagObject } from "../../types.js";
+import { NoReferenceSwallow } from "@fumadocs/api-docs/schema";
 
 //#region src/utils/pages/builder.d.ts
 interface BaseEntry {
@@ -34,6 +32,23 @@ interface OutputGroup extends BaseEntry {
   /** tag info if the group is generated from a tag. */
   tag?: TagObject;
 }
+interface WebhookItem {
+  /**
+   * webhook name in `webhooks`
+   */
+  name: string;
+  method: HttpMethods;
+}
+interface OperationItem {
+  /**
+   * the path of operation in `paths`
+   */
+  path: string;
+  /**
+   * the HTTP method of operation
+   */
+  method: HttpMethods;
+}
 type OutputEntry = PageOutput | OperationOutput | WebhookOutput | OutputGroup;
 interface PagesBuilderConfig {
   toPages: (builder: PagesBuilder) => void;
@@ -43,7 +58,9 @@ interface PagesBuilder {
    * the input ID in OpenAPI server
    */
   id: string;
-  document: DereferencedDocument;
+  /** bundled OpenAPI document (not dereferenced) */
+  document: Document;
+  dereferenceShallow: <T>(schema: T) => NoReferenceSwallow<T>;
   /**
    * add output entry.
    */
@@ -58,13 +75,13 @@ interface PagesBuilder {
   extract: () => ExtractedInfo;
   fromExtractedWebhook: (item: WebhookItem) => {
     get displayName(): string;
-    pathItem: NoReference<PathItemObject>;
-    operation: NoReference<OperationObject>;
+    pathItem: PathItemObject;
+    operation: OperationObject;
   } | undefined;
   fromExtractedOperation: (item: OperationItem) => {
     get displayName(): string;
-    pathItem: NoReference<PathItemObject>;
-    operation: NoReference<OperationObject>;
+    pathItem: PathItemObject;
+    operation: OperationObject;
   } | undefined;
   fromTag: (tag: TagObject) => {
     get displayName(): string;
@@ -82,5 +99,16 @@ interface ExtractedInfo {
     tags?: string[];
   })[];
 }
+interface GeneratedPageProps {
+  /** schema ID */
+  document: string;
+  showTitle?: boolean;
+  showDescription?: boolean;
+  /**
+   * An array of operations
+   */
+  operations?: OperationItem[];
+  webhooks?: WebhookItem[];
+}
 //#endregion
-export { OperationOutput, OutputEntry, OutputGroup, PageOutput, PagesBuilder, PagesBuilderConfig, WebhookOutput };
+export { GeneratedPageProps, OperationItem, OperationOutput, OutputEntry, OutputGroup, PageOutput, PagesBuilder, PagesBuilderConfig, WebhookItem, WebhookOutput };

package/dist/utils/pages/builder.js

@@ -1,13 +1,14 @@
-import { idToTitle } from "../id-to-title.js";
-import { getTagDisplayName, methodKeys } from "../schema/index.js";
+import { getTagDisplayName, methodKeys } from "../schema.js";
+import { idToTitle } from "@fumadocs/api-docs/utils/id-to-title";
+import { dereferenceShallow } from "@fumadocs/api-docs/schema/dereference";
 //#region src/utils/pages/builder.ts
-function fromSchema(schemaId, processed, config) {
+function fromSchema(schemaId, bundled, config) {
 	const files = [];
 	const { toPages } = config;
-	const { dereferenced } = processed;
 	toPages({
 		id: schemaId,
-		document: processed,
+		document: bundled,
+		dereferenceShallow: (s) => dereferenceShallow(s, bundled),
 		create(entry) {
 			files.push(entry);
 		},
@@ -16,7 +17,7 @@ function fromSchema(schemaId, processed, config) {
 				webhooks: [],
 				operations: []
 			};
-			for (const [path, pathItem] of Object.entries(dereferenced.paths ?? {})) {
+			for (const [path, pathItem] of Object.entries(bundled.paths ?? {})) {
 				if (!pathItem) continue;
 				for (const methodKey of methodKeys) {
 					if (!pathItem[methodKey]) continue;
@@ -27,7 +28,8 @@ function fromSchema(schemaId, processed, config) {
 					});
 				}
 			}
-			for (const [name, pathItem] of Object.entries(dereferenced.webhooks ?? {})) {
+			for (const [name, _pathItem] of Object.entries(bundled.webhooks ?? {})) {
+				const pathItem = dereferenceShallow(_pathItem, bundled);
 				if (!pathItem) continue;
 				for (const methodKey of methodKeys) {
 					if (!pathItem[methodKey]) continue;
@@ -48,7 +50,7 @@ function fromSchema(schemaId, processed, config) {
 			}).join("/");
 		},
 		fromExtractedWebhook(item) {
-			const pathItem = dereferenced.webhooks?.[item.name];
+			const pathItem = dereferenceShallow(bundled.webhooks?.[item.name], bundled);
 			if (!pathItem) return;
 			const operation = pathItem?.[item.method];
 			if (!operation) return;
@@ -61,7 +63,7 @@ function fromSchema(schemaId, processed, config) {
 			};
 		},
 		fromExtractedOperation(item) {
-			const pathItem = dereferenced.paths?.[item.path];
+			const pathItem = dereferenceShallow(bundled.paths?.[item.path], bundled);
 			if (!pathItem) return;
 			const operation = pathItem?.[item.method];
 			if (!operation) return;
@@ -79,7 +81,7 @@ function fromSchema(schemaId, processed, config) {
 			} };
 		},
 		fromTagName(name) {
-			const tag = dereferenced.tags?.find((item) => item.name === name);
+			const tag = bundled.tags?.find((item) => item.name === name);
 			if (!tag) return;
 			return {
 				info: tag,