fumadocs-openapi 11.1.1 → 11.2.1

package/dist/ui/index.d.ts

@@ -8,10 +8,8 @@ import { PlaygroundClientOptions } from "../playground/client.js";
 import { GeneratedPageProps, OperationItem, WebhookItem } from "../utils/pages/builder.js";
 import { Awaitable, Document, HttpMethods, OperationObject, PathItemObject, RenderContext } from "../types.js";
 import { ComponentProps, FC, HTMLAttributes, ReactNode } from "react";
-import { NoReference } from "@fumadocs/api-docs/schema";
 import { ShikiFactory } from "fumadocs-core/highlight/shiki";
 import { BundledTheme, CodeOptionsThemes, CodeToHastOptionsCommon } from "shiki";
-
 //#region src/ui/index.d.ts
 interface GenerateTypeScriptDefinitionsContext {
   name: string;
@@ -22,8 +20,8 @@ interface GenerateTypeScriptDefinitionsContext {
 interface APIPlaygroundProps {
   path: string;
   method: HttpMethods;
-  operation: NoReference<OperationObject>;
-  pathItem: NoReference<PathItemObject>;
+  operation: OperationObject;
+  pathItem: PathItemObject;
   ctx: RenderContext;
 }
 interface CreateOpenAPIPageOptions {
@@ -41,9 +39,9 @@ interface CreateOpenAPIPageOptions {
    * Generate example code usage for each endpoint.
    */
   generateCodeSamples?: (options: {
-    operation: NoReference<OperationObject>;
+    operation: OperationObject;
     method: HttpMethods;
-    pathItem: NoReference<PathItemObject>;
+    pathItem: PathItemObject;
   }) => InlineCodeUsageGenerator[];
   shiki?: ShikiFactory;
   shikiOptions?: Omit<CodeToHastOptionsCommon, 'lang'> & CodeOptionsThemes<BundledTheme>;
@@ -96,9 +94,9 @@ interface CreateOpenAPIPageOptions {
       responses: ReactNode;
       callbacks: ReactNode;
     }, context: {
-      operation: NoReference<OperationObject>;
+      operation: OperationObject;
       method: HttpMethods;
-      pathItem: NoReference<PathItemObject>;
+      pathItem: PathItemObject;
       ctx: RenderContext;
     }) => ReactNode;
     renderWebhookLayout?: (slots: {

package/dist/ui/operation/index.js

@@ -33,8 +33,8 @@ const paramTypeKeys = [
 function Operation({ type = "operation", path, operation, pathItem, method, showTitle, showDescription, headingLevel = 2 }) {
 	const t = useTranslations({ note: "operation page" });
 	const ctx = useRenderContext();
-	const { schema: { dereferenced } } = ctx;
-	const body = operation.requestBody;
+	const { schema: { dereferenced, resolve } } = ctx;
+	const body = resolve(operation.requestBody);
 	let headNode = null;
 	const operationDescription = operation.description ?? pathItem.description;
 	const descriptionNode = showDescription && operationDescription && /* @__PURE__ */ jsx(Markdown, { md: operationDescription });
@@ -110,7 +110,7 @@ function Operation({ type = "operation", path, operation, pathItem, method, show
 						anchorSegments: ["request-body", type],
 						value: type,
 						children: /* @__PURE__ */ jsx(RequestBodyContentItem, {
-							content,
+							content: resolve(content),
 							operation,
 							method
 						})
@@ -133,7 +133,7 @@ function Operation({ type = "operation", path, operation, pathItem, method, show
 			}, status))
 		})] });
 	}
-	const parameters = [...operation.parameters ?? [], ...pathItem.parameters ?? []];
+	const parameters = [...operation.parameters ?? [], ...pathItem.parameters ?? []].map((param) => resolve(param));
 	const parameterNode = paramTypeKeys.map((type) => {
 		const params = parameters.filter((param) => param.in === type);
 		if (!params || params.length === 0) return;
@@ -146,19 +146,23 @@ function Operation({ type = "operation", path, operation, pathItem, method, show
 			segments: ["parameters", type],
 			children: /* @__PURE__ */ jsx("div", {
 				className: "flex flex-col",
-				children: params.map((param) => param.schema != null && /* @__PURE__ */ jsx(ctx.SchemaUI, {
-					client: {
-						name: param.name,
-						required: param.required
-					},
-					root: typeof param.schema === "object" ? {
-						...param.schema,
-						description: param.description ?? param.schema?.description,
-						deprecated: (param.deprecated ?? false) || (param.schema?.deprecated ?? false)
-					} : param.schema,
-					readOnly: method === "get",
-					writeOnly: method !== "get"
-				}, param.name))
+				children: params.map((param) => {
+					if (param.schema == null) return;
+					const schema = resolve(param.schema);
+					return /* @__PURE__ */ jsx(ctx.SchemaUI, {
+						client: {
+							name: param.name,
+							required: param.required
+						},
+						root: typeof schema === "object" ? {
+							...schema,
+							description: param.description ?? schema.description,
+							deprecated: (param.deprecated ?? false) || (schema.deprecated ?? false)
+						} : schema,
+						readOnly: method === "get",
+						writeOnly: method !== "get"
+					}, param.name);
+				})
 			})
 		})] }, type);
 	});
@@ -203,7 +207,7 @@ function Operation({ type = "operation", path, operation, pathItem, method, show
 			}), securities.map((security, i) => /* @__PURE__ */ jsx(SelectTab, {
 				value: items[i].value,
 				children: Object.entries(security).map(([key, scopes]) => {
-					const scheme = securitySchemes?.[key];
+					const scheme = resolve(securitySchemes?.[key]);
 					if (!scheme) return;
 					return /* @__PURE__ */ jsx(AuthScheme, {
 						scheme,
@@ -214,15 +218,21 @@ function Operation({ type = "operation", path, operation, pathItem, method, show
 		});
 	}
 	const webhookCallbacks = [];
-	for (const [name, callbacks] of Object.entries(operation.callbacks ?? {})) for (const [path, callback] of Object.entries(callbacks)) for (const method of methodKeys) {
-		if (!callback[method]) continue;
-		webhookCallbacks.push({
-			name,
-			path,
-			method,
-			callback,
-			operation: callback[method]
-		});
+	for (const [name, item] of Object.entries(operation.callbacks ?? {})) {
+		const callbacks = resolve(item);
+		for (const [path, pathItem] of Object.entries(callbacks)) {
+			const callback = resolve(pathItem);
+			for (const method of methodKeys) {
+				if (!callback[method]) continue;
+				webhookCallbacks.push({
+					name,
+					path,
+					method,
+					callback,
+					operation: callback[method]
+				});
+			}
+		}
 	}
 	if (webhookCallbacks.length > 0) callbacksNode = /* @__PURE__ */ jsxs(Fragment$1, { children: [/* @__PURE__ */ jsx(Heading, {
 		id: "callbacks",
@@ -399,7 +409,7 @@ function RequestBodyContentItem({ content, method, operation }) {
 		client: {
 			name: "body",
 			as: "body",
-			required: operation.requestBody?.required
+			required: ctx.schema.resolve(operation.requestBody)?.required
 		},
 		root: content.schema,
 		readOnly: method === "get",
@@ -407,7 +417,8 @@ function RequestBodyContentItem({ content, method, operation }) {
 	})] });
 }
 function ResponseAccordion({ status, operation }) {
-	const response = operation.responses[status];
+	const { schema } = useRenderContext();
+	const response = schema.resolve(operation.responses[status]);
 	const contentTypes = response.content ? Object.entries(response.content) : [];
 	const items = contentTypes.map(([key]) => ({
 		label: /* @__PURE__ */ jsx("code", {
@@ -439,7 +450,7 @@ function ResponseAccordion({ status, operation }) {
 				}), contentTypes.map(([type, item]) => /* @__PURE__ */ jsx(SelectTab, {
 					value: type,
 					anchorSegments: [type],
-					children: /* @__PURE__ */ jsx(RepsonseAccordionItem, { item })
+					children: /* @__PURE__ */ jsx(RepsonseAccordionItem, { item: schema.resolve(item) })
 				}, type))]
 			})]
 		})

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

@@ -1,15 +1,13 @@
 import { ExampleRequestItem } from "../../utils/get-example-requests.js";
 import { HttpMethods, OperationObject, PathItemObject } from "../../types.js";
 import { ReactNode } from "react";
-import { NoReference } from "@fumadocs/api-docs/schema";
-
 //#region src/ui/operation/request-tabs.d.ts
 interface RequestTabsRenderOptions {
   route: string;
   items: ExampleRequestItem[];
   method: HttpMethods;
-  pathItem: NoReference<PathItemObject>;
-  operation: NoReference<OperationObject>;
+  pathItem: PathItemObject;
+  operation: OperationObject;
 }
 //#endregion
 export { RequestTabsRenderOptions };

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

@@ -1,14 +1,12 @@
 import { ResponseObject } from "../../types.js";
 import { ReactNode } from "react";
-import { NoReference } from "@fumadocs/api-docs/schema";
-
 //#region src/ui/operation/response-tabs.d.ts
 interface ResponseTab {
   /**
    * HTTP response code
    */
   code: string;
-  response: NoReference<ResponseObject>;
+  response: ResponseObject;
   /**
    * media type of response
    */

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

@@ -3,6 +3,7 @@ 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 { getRaw } from "@scalar/json-magic/magic-proxy";
 import { useMemo } from "react";
 import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
 import { useTranslations } from "@fuma-translate/react";
@@ -12,13 +13,15 @@ import { sample } from "@fumadocs/api-docs/schema/sample";
 //#region src/ui/operation/response-tabs.tsx
 function ResponseTabs({ operation }) {
 	const ctx = useRenderContext();
+	const { resolve } = ctx.schema;
 	const t = useTranslations({ note: "operation page" });
 	const tabs = useMemo(() => {
 		const tabs = [];
 		if (!operation.responses) return tabs;
-		for (const [code, response] of Object.entries(operation.responses)) {
+		for (const [code, item] of Object.entries(operation.responses)) {
+			const response = resolve(item);
 			const media = response.content ? getPreferredType(response.content) : null;
-			const responseOfType = media ? response.content?.[media] : null;
+			const responseOfType = media ? resolve(response.content?.[media]) : null;
 			const tab = {
 				code,
 				response,
@@ -26,22 +29,29 @@ function ResponseTabs({ operation }) {
 			};
 			if (responseOfType?.examples) {
 				tab.examples ??= [];
-				for (const [key, sample] of Object.entries(responseOfType.examples)) tab.examples.push({
-					label: sample?.summary ?? t("Example {key}", { variables: { key } }),
-					sample: sample.value,
-					description: sample?.description
-				});
+				for (const [key, item] of Object.entries(responseOfType.examples)) {
+					const example = resolve(item);
+					tab.examples.push({
+						label: example?.summary ?? t("Example {key}", { variables: { key } }),
+						sample: getRaw(example.value),
+						description: example?.description
+					});
+				}
 			} else if (responseOfType?.example || responseOfType?.schema) {
 				tab.examples ??= [];
 				tab.examples.push({
 					label: t("Example"),
-					sample: responseOfType.example ?? sample(responseOfType.schema)
+					sample: getRaw(responseOfType.example) ?? sample(responseOfType.schema)
 				});
 			}
 			tabs.push(tab);
 		}
 		return tabs;
-	}, [operation.responses, t]);
+	}, [
+		operation.responses,
+		resolve,
+		t
+	]);
 	if (tabs.length === 0) return null;
 	const { renderResponseTabs = renderResponseTabsDefault } = ctx.content ?? {};
 	return renderResponseTabs({ tabs }, ctx);

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

@@ -1,16 +1,19 @@
 import { Document } from "../../types.js";
-import { NoReference } from "@fumadocs/api-docs/schema";
-
+import { NoReferenceSwallow } from "@fumadocs/api-docs/schema";
 //#region src/utils/document/dereference.d.ts
 interface DereferencedDocument {
   /**
-   * dereferenced document
+   * document wrapped in a magic proxy (`@scalar/json-magic`).
+   *
+   * Reference Objects remain in the document — resolve them lazily with {@link resolve}.
    */
-  dereferenced: NoReference<Document>;
+  dereferenced: Document;
   /**
-   * Get raw $ref from dereferenced object
+   * Shallowly resolve a Reference Object from the document, merging sibling keywords.
+   *
+   * Non-reference values are returned as-is.
    */
-  getRawRef: (obj: object) => string | undefined;
+  resolve: <T>(node: T) => NoReferenceSwallow<T>;
   bundled: Document;
 }
 //#endregion

package/dist/utils/document/dereference.js

@@ -1,14 +1,12 @@
-import { dereferenceSync } from "@fumadocs/api-docs/schema/dereference";
+import { dereferenceShallow } from "@fumadocs/api-docs/schema/dereference";
+import { createMagicProxy } from "@scalar/json-magic/magic-proxy";
 //#region src/utils/document/dereference.ts
 function dereferenceBundledDocument(bundled) {
-	const dereferenceMap = /* @__PURE__ */ new Map();
 	return {
 		bundled,
-		dereferenced: dereferenceSync(bundled, { setOriginalRef(schema, ref) {
-			dereferenceMap.set(schema, ref);
-		} }),
-		getRawRef(obj) {
-			return dereferenceMap.get(obj);
+		dereferenced: createMagicProxy(bundled),
+		resolve(node) {
+			return dereferenceShallow(node);
 		}
 	};
 }

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

@@ -1,6 +1,5 @@
 import { RawRequestData, RequestData } from "../requests/types.js";
-import { NoReference } from "@fumadocs/api-docs/schema";
-
+import "../types.js";
 //#region src/utils/get-example-requests.d.ts
 interface ExampleRequestItem {
   id: string;

package/dist/utils/get-example-requests.js

@@ -1,26 +1,29 @@
 import { getPreferredType, pickExample } from "./schema.js";
 import { encodeRequestData } from "../requests/media/encode.js";
+import { dereferenceShallow } from "@fumadocs/api-docs/schema/dereference";
+import { getRaw } from "@scalar/json-magic/magic-proxy";
 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 requestBody = dereferenceShallow(operation.requestBody);
 	const media = requestBody?.content ? getPreferredType(requestBody.content) : null;
-	const bodyOfType = media ? requestBody.content[media] : null;
-	const parameters = [...operation.parameters ?? [], ...pathItem.parameters ?? []];
+	const bodyOfType = media ? dereferenceShallow(requestBody.content[media]) : null;
+	const parameters = [...operation.parameters ?? [], ...pathItem.parameters ?? []].map(dereferenceShallow);
 	if (bodyOfType?.examples) {
 		const result = [];
-		for (const [key, value] of Object.entries(bodyOfType.examples)) {
+		for (const [key, item] of Object.entries(bodyOfType.examples)) {
+			const { summary, description } = dereferenceShallow(item);
 			const data = getRequestData({
 				path,
-				body: operation.requestBody,
+				body: requestBody,
 				parameters,
 				sampleKey: key,
 				method
 			});
 			result.push({
 				id: key,
-				name: value.summary || key,
-				description: value.description,
+				name: summary || key,
+				description,
 				data,
 				encoded: encodeRequestData(data, ctx.mediaAdapters, parameters)
 			});
@@ -29,14 +32,15 @@ function getExampleRequests({ path, method, ctx, operation, pathItem }) {
 	}
 	const data = getRequestData({
 		path,
-		body: operation.requestBody,
+		body: requestBody,
 		method,
 		parameters
 	});
+	const schema = dereferenceShallow(bodyOfType?.schema);
 	return [{
 		id: "_default",
 		name: "Default",
-		description: typeof bodyOfType?.schema === "object" ? bodyOfType.schema.description : void 0,
+		description: typeof schema === "object" ? schema.description : void 0,
 		data,
 		encoded: encodeRequestData(data, ctx.mediaAdapters, parameters)
 	}];
@@ -55,7 +59,7 @@ function getRequestData({ method, path, parameters, sampleKey, body }) {
 			if (param.schema) value = sample(param.schema);
 			else if (param.content) {
 				const type = getPreferredType(param.content);
-				const content = type ? param.content[type] : void 0;
+				const content = type ? dereferenceShallow(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}`);
 				value = sample(content.schema);
 			}
@@ -77,9 +81,9 @@ function getRequestData({ method, path, parameters, sampleKey, body }) {
 		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.content[type];
-		if (bodyOfType.examples && sampleKey) result.body = bodyOfType.examples[sampleKey].value;
-		else if (bodyOfType.example) result.body = bodyOfType.example;
+		const bodyOfType = dereferenceShallow(body.content[type]);
+		if (bodyOfType.examples && sampleKey) result.body = getRaw(dereferenceShallow(bodyOfType.examples[sampleKey]).value);
+		else if (bodyOfType.example) result.body = getRaw(bodyOfType.example);
 		else result.body = sample(bodyOfType?.schema ?? {}, {
 			skipReadOnly: method !== "get",
 			skipWriteOnly: method === "get",

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

@@ -1,6 +1,5 @@
 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 {
   path: string;

package/dist/utils/pages/builder.js

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

package/dist/utils/pages/preset-auto.d.ts

@@ -1,6 +1,5 @@
 import { OperationOutput, PageOutput, PagesBuilder, PagesBuilderConfig, WebhookOutput } from "./builder.js";
 import { DistributiveOmit } from "../../types.js";
-
 //#region src/utils/pages/preset-auto.d.ts
 interface OperationConfig extends BaseConfig {
   /**

package/dist/utils/pages/preset-auto.js

@@ -21,7 +21,7 @@ function createAutoPreset(options) {
 				if (algorithm === "v2" && operation.operationId) return operation.operationId;
 				return path$1.join(this.routePathToFilePath(result.item.path), result.item.method.toLowerCase());
 			}
-			const hook = dereferenceShallow(this.document.webhooks[result.item.name], this.document)[result.item.method];
+			const hook = dereferenceShallow(this.document.webhooks[result.item.name])[result.item.method];
 			if (algorithm === "v2" && hook.operationId) return hook.operationId;
 			return slugify(result.item.name);
 		};
@@ -52,7 +52,7 @@ function createAutoPreset(options) {
 				break;
 			}
 			case "tag": {
-				let tags = entry.type === "operation" ? dereferenceShallow(doc.paths?.[entry.item.path], doc)?.[entry.item.method]?.tags : dereferenceShallow(doc.webhooks?.[entry.item.name], doc)?.[entry.item.method]?.tags;
+				let tags = entry.type === "operation" ? dereferenceShallow(doc.paths?.[entry.item.path])?.[entry.item.method]?.tags : dereferenceShallow(doc.webhooks?.[entry.item.name])?.[entry.item.method]?.tags;
 				if (!tags || tags.length === 0) {
 					console.warn("When `groupBy` is set to `tag`, make sure a `tags` is defined for every operation schema.");
 					tags = ["unknown"];

package/dist/utils/pages/to-static-data.js

@@ -1,8 +1,10 @@
 import { idToTitle } from "@fumadocs/api-docs/utils/id-to-title";
 import { dereferenceShallow } from "@fumadocs/api-docs/schema/dereference";
+import { createMagicProxy } from "@scalar/json-magic/magic-proxy";
 import Slugger from "github-slugger";
 //#region src/utils/pages/to-static-data.ts
 function toStaticData(page, doc) {
+	const proxied = createMagicProxy(doc);
 	const slugger = new Slugger();
 	const toc = [];
 	const structuredData = {
@@ -29,12 +31,12 @@ function toStaticData(page, doc) {
 		});
 	}
 	for (const item of page.operations ?? []) {
-		const operation = dereferenceShallow(doc.paths?.[item.path], doc)?.[item.method];
+		const operation = dereferenceShallow(proxied.paths?.[item.path])?.[item.method];
 		if (!operation) continue;
 		pathItem(operation, item.path);
 	}
 	for (const item of page.webhooks ?? []) {
-		const webhook = dereferenceShallow(doc.webhooks?.[item.name], doc)?.[item.method];
+		const webhook = dereferenceShallow(proxied.webhooks?.[item.name])?.[item.method];
 		if (!webhook) continue;
 		pathItem(webhook, item.name);
 	}

package/dist/utils/pages/to-text.d.ts

@@ -1,5 +1,5 @@
+import "./builder.js";
 import { TagObject } from "../../types.js";
-
 //#region src/utils/pages/to-text.d.ts
 interface PagesToTextOptions {
   /**

package/dist/utils/pages/to-text.js

@@ -1,8 +1,7 @@
 import { getPageProps } from "./builder.js";
 import { toStaticData } from "./to-static-data.js";
 import { doubleQuote } from "../../requests/string-utils.js";
-import { removeUndefined } from "../remove-undefined.js";
-import { dump } from "js-yaml";
+import { stringify } from "yaml";
 //#region src/utils/pages/to-text.ts
 function toText(entry, doc, options = {}) {
 	const { frontmatter, includeDescription = false } = options;
@@ -34,7 +33,10 @@ function toText(entry, doc, options = {}) {
 function generateDocument(frontmatter, content, options) {
 	const { addGeneratedComment = true, imports } = options;
 	const out = [];
-	const banner = dump(removeUndefined(frontmatter)).trimEnd();
+	const banner = stringify(frontmatter, {
+		compat: "yaml-1.1",
+		singleQuote: true
+	}).trimEnd();
 	if (banner.length > 0) out.push(`---\n${banner}\n---`);
 	if (addGeneratedComment) {
 		let commentContent = "This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again.";

package/dist/utils/schema.d.ts

@@ -1,2 +1,3 @@
+import "../types.js";
 import { ParsedSchema } from "@fumadocs/api-docs/schema";
 export type { ParsedSchema };

package/dist/utils/schema.js

@@ -1,4 +1,6 @@
 import { idToTitle } from "@fumadocs/api-docs/utils/id-to-title";
+import { dereferenceShallow } from "@fumadocs/api-docs/schema/dereference";
+import { getRaw } from "@scalar/json-magic/magic-proxy";
 //#region src/utils/schema.ts
 const methodKeys = [
 	"get",
@@ -18,18 +20,19 @@ function getTagDisplayName(tag) {
 	return idToTitle(tag.name);
 }
 function pickExample(value) {
-	if (value.example !== void 0) return value.example;
+	if (value.example !== void 0) return getRaw(value.example);
 	if (value.content) {
 		const type = getPreferredType(value.content);
-		const content = type ? value.content[type] : void 0;
+		const content = type ? dereferenceShallow(value.content[type]) : void 0;
 		if (type && content) {
-			const out = value.examples?.[type].value ?? pickExample(content);
+			const example = value.examples?.[type];
+			const out = (example !== void 0 ? getRaw(dereferenceShallow(example).value) : void 0) ?? pickExample(content);
 			if (out !== void 0) return out;
 		}
 	}
 	if (value.examples) {
 		const examples = Object.values(value.examples);
-		if (examples.length > 0) return examples[0].value;
+		if (examples.length > 0) return getRaw(dereferenceShallow(examples[0]).value);
 	}
 }
 //#endregion

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fumadocs-openapi",
-  "version": "11.1.1",
+  "version": "11.2.1",
   "description": "Generate MDX docs for your OpenAPI spec",
   "keywords": [
     "Docs",
@@ -44,33 +44,34 @@
   },
   "dependencies": {
     "@fuma-translate/react": "^1.0.2",
-    "@fumari/json-schema-ts": "^0.0.2",
+    "@fumari/json-schema-ts": "^1.0.2",
+    "@scalar/json-magic": "^0.12.17",
     "chokidar": "^5.0.0",
     "class-variance-authority": "^0.7.1",
     "cnfast": "^0.0.8",
     "github-slugger": "^2.0.0",
     "hast-util-to-jsx-runtime": "^2.3.6",
-    "js-yaml": "^5.2.1",
-    "lucide-react": "^1.23.0",
+    "lucide-react": "^1.24.0",
     "remark": "^15.0.1",
     "remark-rehype": "^11.1.2",
     "shiki": "^4.3.1",
-    "@fumadocs/api-docs": "0.1.0",
+    "yaml": "^2.9.0",
+    "@fumadocs/api-docs": "0.2.0",
     "@fumari/stf": "1.1.0"
   },
   "devDependencies": {
-    "@scalar/api-client-react": "^2.0.31",
+    "@scalar/api-client-react": "^2.0.32",
     "@scalar/openapi-upgrader": "^0.2.9",
     "@tailwindcss/oxide": "^4.3.2",
-    "@types/node": "26.1.0",
+    "@types/node": "26.1.1",
     "@types/react": "^19.2.17",
     "fast-content-type-parse": "^3.0.0",
     "json-schema-typed": "^8.0.2",
-    "tsdown": "0.22.3",
+    "tsdown": "0.22.5",
     "xml-js": "^1.6.11",
-    "fumadocs-core": "16.11.1",
     "tsconfig": "0.0.0",
-    "fumadocs-ui": "npm:@fumadocs/base-ui@16.11.1"
+    "fumadocs-core": "16.11.5",
+    "fumadocs-ui": "npm:@fumadocs/base-ui@16.11.5"
   },
   "peerDependencies": {
     "@scalar/api-client-react": "^2.0.20",