fumadocs-openapi 11.4.2 → 12.0.0

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

@@ -1,18 +1,16 @@
 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";
+import { dereference, sample } from "@fumadocs/json-schema";
 //#region src/utils/get-example-requests.ts
-function getExampleRequests({ path, method, ctx, operation, pathItem }) {
-	const requestBody = dereferenceShallow(operation.requestBody);
+function getExampleRequests({ path, method, mediaAdapters, operation, parameters }) {
+	const requestBody = dereference(operation.requestBody);
 	const media = requestBody?.content ? getPreferredType(requestBody.content) : null;
-	const bodyOfType = media ? dereferenceShallow(requestBody.content[media]) : null;
-	const parameters = [...operation.parameters ?? [], ...pathItem.parameters ?? []].map(dereferenceShallow);
+	const bodyOfType = media ? dereference(requestBody.content[media]) : null;
 	if (bodyOfType?.examples) {
 		const result = [];
 		for (const [key, item] of Object.entries(bodyOfType.examples)) {
-			const { summary, description } = dereferenceShallow(item);
+			const { summary, description } = dereference(item);
 			const data = getRequestData({
 				path,
 				body: requestBody,
@@ -25,7 +23,7 @@ function getExampleRequests({ path, method, ctx, operation, pathItem }) {
 				name: summary || key,
 				description,
 				data,
-				encoded: encodeRequestData(data, ctx.mediaAdapters, parameters)
+				encoded: encodeRequestData(data, mediaAdapters, parameters)
 			});
 		}
 		if (result.length > 0) return result;
@@ -36,13 +34,13 @@ function getExampleRequests({ path, method, ctx, operation, pathItem }) {
 		method,
 		parameters
 	});
-	const schema = dereferenceShallow(bodyOfType?.schema);
+	const schema = dereference(bodyOfType?.schema);
 	return [{
 		id: "_default",
 		name: "Default",
 		description: typeof schema === "object" ? schema.description : void 0,
 		data,
-		encoded: encodeRequestData(data, ctx.mediaAdapters, parameters)
+		encoded: encodeRequestData(data, mediaAdapters, parameters)
 	}];
 }
 function getRequestData({ method, path, parameters, sampleKey, body }) {
@@ -59,7 +57,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 ? dereferenceShallow(param.content[type]) : void 0;
+				const content = type ? dereference(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);
 			}
@@ -81,8 +79,8 @@ 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 = dereferenceShallow(body.content[type]);
-		if (bodyOfType.examples && sampleKey) result.body = getRaw(dereferenceShallow(bodyOfType.examples[sampleKey]).value);
+		const bodyOfType = dereference(body.content[type]);
+		if (bodyOfType.examples && sampleKey) result.body = getRaw(dereference(bodyOfType.examples[sampleKey]).value);
 		else if (bodyOfType.example) result.body = getRaw(bodyOfType.example);
 		else result.body = sample(bodyOfType?.schema ?? {}, {
 			skipReadOnly: method !== "get",

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

@@ -1,5 +1,5 @@
 import { Document, HttpMethods, OperationObject, PathItemObject, TagObject } from "../../types.js";
-import { NoReferenceSwallow } from "@fumadocs/api-docs/schema";
+import { DereferencedShallow } from "@fumadocs/json-schema";
 //#region src/utils/pages/builder.d.ts
 interface BaseEntry {
   path: string;
@@ -59,7 +59,7 @@ export interface PagesBuilder {
   id: string;
   /** bundled OpenAPI document (not dereferenced) */
   document: Document;
-  dereferenceShallow: <T>(schema: T) => NoReferenceSwallow<T>;
+  dereferenceShallow: <T>(schema: T) => DereferencedShallow<T>;
   /**
    * add output entry.
    */
@@ -109,4 +109,17 @@ export interface GeneratedPageProps {
   operations?: OperationItem[];
   webhooks?: WebhookItem[];
 }
+export type OpenAPIPageProps = OpenAPIPageProps_Spec | OpenAPIPageProps_Preloaded;
+export type OpenAPIPageProps_Spec = Omit<GeneratedPageProps, 'document'> & {
+  payload: {
+    bundled: Document;
+    proxyUrl?: string;
+  };
+};
+export type OpenAPIPageProps_Preloaded = GeneratedPageProps & {
+  preloaded: {
+    docs: Record<string, Document>;
+    proxyUrl?: string;
+  };
+};
 //#endregion

package/dist/utils/pages/builder.js

@@ -1,7 +1,7 @@
+import { idToTitle } from "../../packages/shared-api/dist/utils/id-to-title.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";
 import { createMagicProxy } from "@scalar/json-magic/magic-proxy";
+import { dereference } from "@fumadocs/json-schema";
 //#region src/utils/pages/builder.ts
 function fromSchema(schemaId, bundled, config) {
 	const files = [];
@@ -10,7 +10,7 @@ function fromSchema(schemaId, bundled, config) {
 	toPages({
 		id: schemaId,
 		document,
-		dereferenceShallow: (s) => dereferenceShallow(s),
+		dereferenceShallow: (s) => dereference(s),
 		create(entry) {
 			files.push(entry);
 		},
@@ -31,7 +31,7 @@ function fromSchema(schemaId, bundled, config) {
 				}
 			}
 			for (const [name, _pathItem] of Object.entries(document.webhooks ?? {})) {
-				const pathItem = dereferenceShallow(_pathItem);
+				const pathItem = dereference(_pathItem);
 				if (!pathItem) continue;
 				for (const methodKey of methodKeys) {
 					if (!pathItem[methodKey]) continue;
@@ -52,7 +52,7 @@ function fromSchema(schemaId, bundled, config) {
 			}).join("/");
 		},
 		fromExtractedWebhook(item) {
-			const pathItem = dereferenceShallow(document.webhooks?.[item.name]);
+			const pathItem = dereference(document.webhooks?.[item.name]);
 			if (!pathItem) return;
 			const operation = pathItem?.[item.method];
 			if (!operation) return;
@@ -65,7 +65,7 @@ function fromSchema(schemaId, bundled, config) {
 			};
 		},
 		fromExtractedOperation(item) {
-			const pathItem = dereferenceShallow(document.paths?.[item.path]);
+			const pathItem = dereference(document.paths?.[item.path]);
 			if (!pathItem) return;
 			const operation = pathItem?.[item.method];
 			if (!operation) return;

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

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

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

@@ -1,6 +1,6 @@
 import { getTagDisplayName } from "../schema.js";
+import { dereference } from "@fumadocs/json-schema";
 import * as path$1 from "node:path";
-import { dereferenceShallow } from "@fumadocs/api-docs/schema/dereference";
 //#region src/utils/pages/preset-auto.ts
 function createAutoPreset(options) {
 	if (options.per === "custom") return options;
@@ -22,7 +22,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])[result.item.method];
+			const hook = dereference(this.document.webhooks[result.item.name])[result.item.method];
 			if (algorithm === "v2" && hook.operationId) return hook.operationId;
 			return slugify(result.item.name);
 		};
@@ -83,7 +83,7 @@ function createAutoPreset(options) {
 				break;
 			}
 			case "tag": {
-				const operation = entry.type === "operation" ? dereferenceShallow(doc.paths?.[entry.item.path])?.[entry.item.method] : dereferenceShallow(doc.webhooks?.[entry.item.name])?.[entry.item.method];
+				const operation = entry.type === "operation" ? dereference(doc.paths?.[entry.item.path])?.[entry.item.method] : dereference(doc.webhooks?.[entry.item.name])?.[entry.item.method];
 				const tags = [];
 				for (const name of operation?.tags ?? []) {
 					const kind = docTags.get(name)?.kind;

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

@@ -1,6 +1,6 @@
-import { idToTitle } from "@fumadocs/api-docs/utils/id-to-title";
-import { dereferenceShallow } from "@fumadocs/api-docs/schema/dereference";
+import { idToTitle } from "../../packages/shared-api/dist/utils/id-to-title.js";
 import { createMagicProxy } from "@scalar/json-magic/magic-proxy";
+import { dereference } from "@fumadocs/json-schema";
 import Slugger from "github-slugger";
 //#region src/utils/pages/to-static-data.ts
 const proxyCache = /* @__PURE__ */ new WeakMap();
@@ -36,12 +36,12 @@ function toStaticData(page, doc) {
 		});
 	}
 	for (const item of page.operations ?? []) {
-		const operation = dereferenceShallow(proxied.paths?.[item.path])?.[item.method];
+		const operation = dereference(proxied.paths?.[item.path])?.[item.method];
 		if (!operation) continue;
 		pathItem(operation, item.path);
 	}
 	for (const item of page.webhooks ?? []) {
-		const webhook = dereferenceShallow(proxied.webhooks?.[item.name])?.[item.method];
+		const webhook = dereference(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";
+import "./builder.js";
 //#region src/utils/pages/to-text.d.ts
 export interface PagesToTextOptions {
   /**

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

@@ -1,6 +1,6 @@
+import { doubleQuote } from "../../requests/string-utils.js";
 import { getPageProps } from "./builder.js";
 import { toStaticData } from "./to-static-data.js";
-import { doubleQuote } from "../../requests/string-utils.js";
 import { stringify } from "yaml";
 //#region src/utils/pages/to-text.ts
 function toText(entry, doc, options = {}) {
@@ -61,13 +61,11 @@ function pageContent({ showTitle, showDescription, document, webhooks, operation
 	if (showTitle) propStrs.push(`showTitle`);
 	if (showDescription) propStrs.push(`showDescription`);
 	return `export default function Layout(props) {
-  const { APIPage, OpenAPIPage } = props.components ?? {};
-  // "APIPage" is the old name from v10, this allows both for backward compatibility
-  const Comp = OpenAPIPage ?? APIPage;
+  const { OpenAPIPage } = props.components ?? {};
   return (
     <>
       {props.children}
-      <Comp ${propStrs.join(" ")} />
+      <OpenAPIPage ${propStrs.join(" ")} />
     </>
   );
 }`;

package/dist/utils/schema.js

@@ -1,6 +1,6 @@
-import { idToTitle } from "@fumadocs/api-docs/utils/id-to-title";
-import { dereferenceShallow } from "@fumadocs/api-docs/schema/dereference";
+import { idToTitle } from "../packages/shared-api/dist/utils/id-to-title.js";
 import { getRaw } from "@scalar/json-magic/magic-proxy";
+import { dereference } from "@fumadocs/json-schema";
 //#region src/utils/schema.ts
 const methodKeys = [
 	"get",
@@ -23,16 +23,16 @@ function pickExample(value) {
 	if (value.example !== void 0) return getRaw(value.example);
 	if (value.content) {
 		const type = getPreferredType(value.content);
-		const content = type ? dereferenceShallow(value.content[type]) : void 0;
+		const content = type ? dereference(value.content[type]) : void 0;
 		if (type && content) {
 			const example = value.examples?.[type];
-			const out = (example !== void 0 ? getRaw(dereferenceShallow(example).value) : void 0) ?? pickExample(content);
+			const out = (example !== void 0 ? getRaw(dereference(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 getRaw(dereferenceShallow(examples[0]).value);
+		if (examples.length > 0) return getRaw(dereference(examples[0]).value);
 	}
 }
 //#endregion

package/dist/utils/use-server.d.ts

@@ -0,0 +1,24 @@
+import { ServerObject } from "../types.js";
+import { ReactNode } from "react";
+//#region src/utils/use-server.d.ts
+export interface SelectedServer {
+  url: string;
+  name?: string;
+  variables: Record<string, string>;
+}
+interface ServerContextType {
+  servers?: ServerObject[];
+  server: SelectedServer | null;
+  /**
+   * The URL of `pathname` on the selected server, with the server variables resolved.
+   *
+   * It is resolved against the page origin, which also serves the request when no server is
+   * selected. On the server and during hydration the origin is unknown, so it is
+   * `https://example.com`.
+   */
+  resolveUrl: (pathname?: string) => string;
+  setServer: (value: string) => void;
+  setServerVariables: (value: Record<string, string>) => void;
+}
+export declare function useServer(): ServerContextType;
+//#endregion

package/dist/utils/use-server.js

@@ -0,0 +1,57 @@
+"use client";
+import { useServerStore } from "../packages/shared-api/dist/utils/use-server-store.js";
+import { joinURL, resolveServerUrl } from "../packages/shared-api/dist/utils/url.js";
+import { createContext, use, useCallback, useMemo, useSyncExternalStore } from "react";
+import { jsx } from "react/jsx-runtime";
+//#region src/utils/use-server.tsx
+const ServerContext = createContext(null);
+const keyOfServer = (server) => server.url;
+const noop = () => () => {};
+function useServer() {
+	const ctx = use(ServerContext);
+	if (!ctx) throw new Error("Component must be used under <OpenAPIProvider />");
+	return ctx;
+}
+function ServerProvider({ servers, storageKeyPrefix, children }) {
+	const resolve = useCallback((url) => {
+		const server = servers?.find((item) => item.url === url);
+		if (!server) return null;
+		return {
+			name: server.name,
+			url,
+			variables: getDefaultValues(server)
+		};
+	}, [servers]);
+	const store = useServerStore({
+		storageKey: `${storageKeyPrefix}server-url`,
+		keyOf: keyOfServer,
+		resolve,
+		defaultKey: servers?.[0]?.url
+	});
+	const { server } = store;
+	const isClient = useSyncExternalStore(noop, () => true, () => false);
+	const resolveUrl = useCallback((pathname = "") => {
+		const base = isClient ? new URL(server ? resolveServerUrl(server.url, server.variables) : "/", window.location.origin).href : "https://example.com";
+		return pathname ? joinURL(base, pathname) : base;
+	}, [server, isClient]);
+	return /* @__PURE__ */ jsx(ServerContext, {
+		value: useMemo(() => ({
+			servers,
+			resolveUrl,
+			...store
+		}), [
+			servers,
+			resolveUrl,
+			store
+		]),
+		children
+	});
+}
+function getDefaultValues(server) {
+	const out = {};
+	if (!server.variables) return out;
+	for (const [k, v] of Object.entries(server.variables)) if (v.default !== void 0) out[k] = String(v.default);
+	return out;
+}
+//#endregion
+export { ServerProvider, useServer };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fumadocs-openapi",
-  "version": "11.4.2",
+  "version": "12.0.0",
   "description": "Generate MDX docs for your OpenAPI spec",
   "keywords": [
     "Docs",
@@ -18,10 +18,19 @@
     "dist"
   ],
   "type": "module",
+  "sideEffects": [
+    "./css/**/*.css"
+  ],
   "exports": {
-    ".": "./dist/index.js",
+    ".": {
+      "types": "./dist/index.d.ts",
+      "browser": "./dist/index.browser.js",
+      "import": "./dist/index.js"
+    },
     "./i18n": "./dist/i18n.js",
-    "./playground/client": "./dist/playground/client.js",
+    "./operation": "./dist/operation.js",
+    "./playground": "./dist/playground/index.js",
+    "./requests": "./dist/requests/index.js",
     "./requests/generators": "./dist/requests/generators/index.js",
     "./requests/generators/all": "./dist/requests/generators/all.js",
     "./requests/generators/csharp": "./dist/requests/generators/csharp.js",
@@ -31,11 +40,11 @@
     "./requests/generators/javascript": "./dist/requests/generators/javascript.js",
     "./requests/generators/python": "./dist/requests/generators/python.js",
     "./requests/generators/rust": "./dist/requests/generators/rust.js",
-    "./scalar": "./dist/scalar/index.js",
     "./server": "./dist/server/index.js",
     "./ui": "./dist/ui/index.js",
     "./ui/base": "./dist/ui/base.js",
-    "./ui/create-client": "./dist/ui/create-client.js",
+    "./ui/playground/client": "./dist/ui/playground/client.js",
+    "./ui/scalar": "./dist/ui/scalar/index.js",
     "./package.json": "./package.json",
     "./css/*": "./css/*"
   },
@@ -43,36 +52,39 @@
     "access": "public"
   },
   "dependencies": {
+    "@base-ui/react": "^1.8.0",
     "@fuma-translate/react": "^1.0.2",
+    "@fumadocs/json-schema": "0.2.0",
     "@fumari/json-schema-ts": "^1.0.2",
-    "@scalar/json-magic": "^0.13.4",
+    "@fumari/stf": "1.1.1",
+    "@scalar/json-magic": "^0.13.5",
+    "@scalar/openapi-upgrader": "^0.2.16",
     "chokidar": "^5.0.0",
     "class-variance-authority": "^0.7.1",
-    "cn": "^0.2.6",
+    "cn": "^0.3.0",
     "github-slugger": "^2.0.0",
     "hast-util-to-jsx-runtime": "^2.3.6",
-    "lucide-react": "^1.43.0",
+    "lucide-react": "^1.47.0",
     "remark": "^15.0.1",
     "remark-rehype": "^11.1.2",
     "shiki": "^4.4.3",
-    "yaml": "^2.9.0",
-    "@fumadocs/api-docs": "0.2.8",
-    "@fumari/stf": "1.1.0"
+    "yaml": "^2.9.1"
   },
   "devDependencies": {
-    "@scalar/api-client-react": "^2.0.44",
-    "@scalar/openapi-upgrader": "^0.2.15",
+    "@scalar/api-client-react": "^2.0.45",
     "@tailwindcss/oxide": "^4.3.3",
-    "@types/node": "26.5.0",
-    "@types/react": "^19.2.18",
+    "@types/node": "26.6.1",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
     "fast-content-type-parse": "^4.0.0",
     "fuma-cli": "^0.1.1",
+    "fumadocs-core": "16.15.12",
+    "fumadocs-ui": "npm:@fumadocs/base-ui@16.15.12",
     "json-schema-typed": "^8.0.2",
+    "shared-api": "0.2.10",
+    "tsconfig": "0.0.0",
     "tsdown": "0.23.0",
-    "xml-js": "^1.6.11",
-    "fumadocs-core": "16.15.9",
-    "fumadocs-ui": "npm:@fumadocs/base-ui@16.15.9",
-    "tsconfig": "0.0.0"
+    "xml-js": "^1.6.11"
   },
   "peerDependencies": {
     "@scalar/api-client-react": "^2.0.20",
@@ -95,7 +107,6 @@
     }
   },
   "inlinedDependencies": {
-    "@scalar/openapi-upgrader": "0.2.15",
     "fast-content-type-parse": "4.0.0",
     "xml-js": "1.6.11"
   },