fumadocs-openapi 10.10.3 → 11.0.0

package/dist/ui/index.d.ts

@@ -1,10 +1,207 @@
-import { ApiPageProps, OperationItem, WebhookItem } from "./api-page.js";
-import { CreateAPIPageOptions as CreateAPIPageOptions$1, ServerApiPageProps } from "./base.js";
-import { OpenAPIServer } from "../server/index.js";
-import * as _$react_jsx_runtime0 from "react/jsx-runtime";
+import { MediaAdapter } from "../requests/media/adapter.js";
+import { CodeUsageGeneratorRegistry, InlineCodeUsageGenerator } from "../requests/generators/index.js";
+import { ExampleRequestItem } from "../utils/get-example-requests.js";
+import { RequestTabsRenderOptions } from "./operation/request-tabs.js";
+import { ResponseTabsRenderOptions } from "./operation/response-tabs.js";
+import { ParsedSchema } from "../utils/schema.js";
+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
-type CreateAPIPageOptions = Partial<CreateAPIPageOptions$1>;
-declare function createAPIPage(server: OpenAPIServer, options?: CreateAPIPageOptions): (props: ServerApiPageProps) => _$react_jsx_runtime0.JSX.Element;
+interface GenerateTypeScriptDefinitionsContext {
+  readOnly: boolean;
+  writeOnly: boolean;
+  ctx: RenderContext;
+}
+interface APIPlaygroundProps {
+  path: string;
+  method: HttpMethods;
+  operation: NoReference<OperationObject>;
+  pathItem: NoReference<PathItemObject>;
+  ctx: RenderContext;
+}
+interface CreateOpenAPIPageOptions {
+  /**
+   * Generate TypeScript definitions from JSON schema.
+   *
+   * Pass `false` to disable it.
+   */
+  generateTypeScriptDefinitions?: ((schema: ParsedSchema, ctx: GenerateTypeScriptDefinitionsContext) => Awaitable<string | undefined>) | false;
+  /**
+   * Generate example code usage for all endpoints.
+   */
+  codeUsages?: CodeUsageGeneratorRegistry;
+  /**
+   * Generate example code usage for each endpoint.
+   */
+  generateCodeSamples?: (options: {
+    operation: NoReference<OperationObject>;
+    method: HttpMethods;
+    pathItem: NoReference<PathItemObject>;
+  }) => InlineCodeUsageGenerator[];
+  shiki?: ShikiFactory;
+  shikiOptions?: Omit<CodeToHastOptionsCommon, 'lang'> & CodeOptionsThemes<BundledTheme>;
+  /**
+   * Show full response schema instead of only example response & Typescript definitions.
+   *
+   * @default true
+   */
+  showResponseSchema?: boolean;
+  /**
+   * Support other media types.
+   */
+  mediaAdapters?: Record<string, MediaAdapter>;
+  /**
+   * Customize page content.
+   */
+  content?: {
+    renderResponseTabs?: (options: ResponseTabsRenderOptions, ctx: RenderContext) => ReactNode;
+    renderRequestTabs?: (options: RequestTabsRenderOptions, ctx: RenderContext) => ReactNode;
+    renderAPIExampleLayout?: (slots: {
+      selector: ReactNode;
+      usageTabs: ReactNode;
+      responseTabs: ReactNode;
+    }, ctx: RenderContext) => ReactNode;
+    /**
+     * @param generators - codegens for API example usages
+     */
+    renderAPIExampleUsageTabs?: (generators: CodeUsageGeneratorRegistry, ctx: RenderContext) => ReactNode;
+    /**
+     * renderer of the entire page's layout (containing all operations & webhooks UI)
+     */
+    renderPageLayout?: (slots: {
+      operations?: {
+        item: OperationItem;
+        children: ReactNode;
+      }[];
+      webhooks?: {
+        item: WebhookItem;
+        children: ReactNode;
+      }[];
+    }, ctx: RenderContext) => ReactNode;
+    renderOperationLayout?: (slots: {
+      header: ReactNode;
+      description: ReactNode;
+      apiExample: ReactNode;
+      apiPlayground: ReactNode;
+      authSchemes: ReactNode;
+      parameters: ReactNode;
+      body: ReactNode;
+      responses: ReactNode;
+      callbacks: ReactNode;
+    }, context: {
+      operation: NoReference<OperationObject>;
+      method: HttpMethods;
+      pathItem: NoReference<PathItemObject>;
+      ctx: RenderContext;
+    }) => ReactNode;
+    renderWebhookLayout?: (slots: {
+      header: ReactNode;
+      description: ReactNode;
+      authSchemes: ReactNode;
+      parameters: ReactNode;
+      body: ReactNode;
+      requests: ReactNode;
+      responses: ReactNode;
+      callbacks: ReactNode;
+    }) => ReactNode;
+  };
+  /**
+   * Info UI for JSON schemas.
+   */
+  schemaUI?: {
+    render?: (options: {
+      root: ParsedSchema;
+      readOnly?: boolean;
+      writeOnly?: boolean;
+    }, ctx: RenderContext) => ReactNode;
+    /**
+     * Show examples under the generated content of JSON schemas.
+     *
+     * @defaultValue false
+     */
+    showExample?: boolean;
+  };
+  /**
+   * Customize API playground.
+   */
+  playground?: PlaygroundClientOptions & {
+    /**
+     * @defaultValue true
+     */
+    enabled?: boolean;
+    /**
+     * render a page-level provider (useful for handling auth)
+     */
+    provider?: (props: {
+      children: ReactNode;
+    }) => ReactNode;
+    /**
+     * replace the renderer
+     */
+    render?: (props: APIPlaygroundProps) => ReactNode;
+  };
+  operation?: {
+    APIExampleSelector?: FC<{
+      items: ExampleRequestItem[];
+      value: string | undefined;
+      onValueChange: (id: string) => void;
+    }>;
+  };
+  components?: {
+    Heading?: FC<ComponentProps<'h1'> & {
+      id: string;
+      depth: number;
+    }>;
+    CodeBlock?: FC<{
+      lang: string;
+      code: string;
+    }>;
+    Markdown?: FC<{
+      md: string;
+    }>;
+  };
+  /**
+   * Set a prefix for `localStorage` keys.
+   *
+   * Useful when using multiple OpenAPI instances to prevent state conflicts.
+   *
+   * @defaultValue `fumadocs-openapi-`
+   */
+  storageKeyPrefix?: string;
+  /** @deprecated use `components.Heading` instead */
+  renderHeading?: (props: HTMLAttributes<HTMLHeadingElement>, depth: number) => ReactNode;
+  /** @deprecated use `components.CodeBlock` instead */
+  renderCodeBlock?: (props: {
+    lang: string;
+    code: string;
+  }) => ReactNode;
+  /** @deprecated use `components.Markdown` instead */
+  renderMarkdown?: (md: string) => ReactNode;
+}
+type OpenAPIPageProps = OpenAPIPageProps_Spec | OpenAPIPageProps_Preloaded;
+type OpenAPIPageProps_Spec = Omit<GeneratedPageProps, 'document'> & {
+  payload: {
+    bundled: Document;
+    proxyUrl?: string;
+  };
+};
+type OpenAPIPageProps_Preloaded = GeneratedPageProps & {
+  preloaded: {
+    docs: Record<string, Document>;
+    proxyUrl?: string;
+  };
+};
+/**
+ * Create `<OpenAPIPage />` (a client component).
+ */
+declare function createOpenAPIPage(options?: CreateOpenAPIPageOptions): FC<OpenAPIPageProps>;
+/** @deprecated Use `OpenAPIPageProps` instead */
+type ApiPageProps = OpenAPIPageProps;
 //#endregion
-export { type ApiPageProps, CreateAPIPageOptions, type OperationItem, type WebhookItem, createAPIPage };
+export { APIPlaygroundProps, ApiPageProps, CreateOpenAPIPageOptions, GenerateTypeScriptDefinitionsContext, OpenAPIPageProps, OpenAPIPageProps_Preloaded, OpenAPIPageProps_Spec, type OperationItem, type WebhookItem, createOpenAPIPage };

package/dist/ui/index.js

@@ -1,20 +1,15 @@
-import { createAPIPage as createAPIPage$1 } from "./base.js";
-import { FullProvider } from "./client/full.js";
-import { jsx } from "react/jsx-runtime";
+"use client";
+import { createOpenAPIPageBase } from "./base.js";
 import { defaultShikiFactory } from "fumadocs-core/highlight/shiki/full";
 //#region src/ui/index.tsx
-function createAPIPage(server, options = {}) {
-	const APIPage = createAPIPage$1(server, {
-		shiki: defaultShikiFactory,
-		shikiOptions: { themes: {
-			light: "github-light",
-			dark: "github-dark"
-		} },
-		...options
+/**
+* Create `<OpenAPIPage />` (a client component).
+*/
+function createOpenAPIPage(options = {}) {
+	return createOpenAPIPageBase({
+		...options,
+		shiki: options.shiki ?? defaultShikiFactory
 	});
-	return function APIPageFull(props) {
-		return /* @__PURE__ */ jsx(FullProvider, { children: /* @__PURE__ */ jsx(APIPage, { ...props }) });
-	};
 }
 //#endregion
-export { createAPIPage };
+export { createOpenAPIPage };

package/dist/ui/operation/context.js

@@ -0,0 +1,48 @@
+"use client";
+import { createContext, use, useMemo, useRef, useState } from "react";
+import { jsx } from "react/jsx-runtime";
+//#region src/ui/operation/context.tsx
+const OperationContext = createContext(null);
+function OperationProvider({ route, examples, defaultExampleId, children }) {
+	const [example, setExample] = useState(() => defaultExampleId ?? examples.at(0)?.id);
+	const listeners = useRef([]);
+	return /* @__PURE__ */ jsx(OperationContext, {
+		value: useMemo(() => ({
+			example,
+			route,
+			setExample(newKey) {
+				const example = examples.find((example) => example.id === newKey);
+				if (!example) return;
+				setExample(newKey);
+				for (const listener of listeners.current) listener(example.data, example.encoded);
+			},
+			examples,
+			setExampleData(data, encoded) {
+				for (const item of examples) if (item.id === example) {
+					item.data = data;
+					item.encoded = encoded;
+					break;
+				}
+				for (const listener of listeners.current) listener(data, encoded);
+			},
+			removeListener(listener) {
+				listeners.current = listeners.current.filter((item) => item !== listener);
+			},
+			addListener(listener) {
+				const active = examples.find((item) => item.id === example);
+				listener(active.data, active.encoded);
+				listeners.current.push(listener);
+			}
+		}), [
+			example,
+			route,
+			examples
+		]),
+		children
+	});
+}
+function useOperationContext() {
+	return use(OperationContext);
+}
+//#endregion
+export { OperationProvider, useOperationContext };