fumadocs-openapi 3.2.0 → 4.0.0

package/dist/chunk-RSFOKBAM.js

@@ -0,0 +1,115 @@
+// src/ui/shared.ts
+import { cva } from "class-variance-authority";
+var badgeVariants = cva(
+  "rounded border px-1.5 py-1 text-xs font-medium leading-[12px]",
+  {
+    variants: {
+      color: {
+        green: "border-green-400/50 bg-green-400/20 text-green-600 dark:text-green-400",
+        yellow: "border-yellow-400/50 bg-yellow-400/20 text-yellow-600 dark:text-yellow-400",
+        red: "border-red-400/50 bg-red-400/20 text-red-600 dark:text-red-400",
+        blue: "border-blue-400/50 bg-blue-400/20 text-blue-600 dark:text-blue-400",
+        orange: "border-orange-400/50 bg-orange-400/20 text-orange-600 dark:text-orange-400"
+      }
+    }
+  }
+);
+function getBadgeColor(method) {
+  switch (method) {
+    case "PUT":
+      return "yellow";
+    case "PATCH":
+      return "orange";
+    case "POST":
+      return "blue";
+    case "DELETE":
+      return "red";
+    default:
+      return "green";
+  }
+}
+function getDefaultValue(item, references) {
+  if (item.type === "object")
+    return Object.fromEntries(
+      Object.entries(item.properties).map(([key, prop]) => [
+        key,
+        getDefaultValue(references[prop.schema], references)
+      ])
+    );
+  if (item.type === "array") return [];
+  if (item.type === "null") return null;
+  if (item.type === "switcher")
+    return getDefaultValue(
+      resolve(Object.values(item.items)[0], references),
+      references
+    );
+  return String(item.defaultValue);
+}
+function getDefaultValues(field, context) {
+  return Object.fromEntries(
+    field.map((p) => [p.name, getDefaultValue(p, context)])
+  );
+}
+function resolve(schema, references) {
+  if (typeof schema === "string") return references[schema];
+  if (schema.type !== "ref") return schema;
+  return {
+    ...references[schema.schema],
+    description: schema.description,
+    isRequired: schema.isRequired
+  };
+}
+
+// src/ui/contexts/api.tsx
+import { createContext, useContext, useEffect, useState } from "react";
+import { jsx } from "react/jsx-runtime";
+var ApiContext = createContext({
+  baseUrl: void 0,
+  setBaseUrl: () => void 0,
+  highlighter: null
+});
+function useApiContext() {
+  return useContext(ApiContext);
+}
+async function initHighlighter() {
+  const { createHighlighterCore } = await import("shiki/core");
+  const getWasm = await import("shiki/wasm");
+  return createHighlighterCore({
+    themes: [
+      import("shiki/themes/github-light.mjs"),
+      import("shiki/themes/github-dark.mjs")
+    ],
+    langs: [import("shiki/langs/json.mjs")],
+    loadWasm: getWasm
+  });
+}
+var highlighterInstance;
+function ApiProvider({
+  defaultBaseUrl,
+  children
+}) {
+  const [highlighter, setHighlighter] = useState(null);
+  const [baseUrl, setBaseUrl] = useState(defaultBaseUrl);
+  useEffect(() => {
+    setBaseUrl((prev) => localStorage.getItem("apiBaseUrl") ?? prev);
+    if (highlighterInstance) setHighlighter(highlighterInstance);
+    else
+      void initHighlighter().then((res) => {
+        setHighlighter(res);
+      });
+  }, []);
+  useEffect(() => {
+    if (baseUrl) localStorage.setItem("apiBaseUrl", baseUrl);
+  }, [baseUrl]);
+  return /* @__PURE__ */ jsx(ApiContext.Provider, { value: { baseUrl, setBaseUrl, highlighter }, children });
+}
+
+export {
+  badgeVariants,
+  getBadgeColor,
+  getDefaultValue,
+  getDefaultValues,
+  resolve,
+  useApiContext,
+  ApiProvider
+};

package/dist/index.d.ts

@@ -1,4 +1,6 @@
 import { OpenAPIV3 } from 'openapi-types';
+import { A as APIPlaygroundProps } from './playground-D8pYn13F.js';
+export { P as PrimitiveRequestField, a as ReferenceSchema, R as RequestSchema } from './playground-D8pYn13F.js';
 
 interface ResponsesProps {
     items: string[];
@@ -24,8 +26,11 @@ interface RequestProps {
     name: string;
     code: string;
 }
+interface RootProps {
+    baseUrl?: string;
+}
 interface Renderer {
-    Root: (child: string[]) => string;
+    Root: (props: RootProps, child: string[]) => string;
     API: (child: string[]) => string;
     APIInfo: (props: APIInfoProps, child: string[]) => string;
     APIExample: (child: string[]) => string;
@@ -41,7 +46,9 @@ interface Renderer {
      */
     ObjectCollapsible: (props: ObjectCollapsibleProps, child: string[]) => string;
     Property: (props: PropertyProps, child: string[]) => string;
+    APIPlayground: (props: APIPlaygroundProps) => string;
 }
+
 declare const defaultRenderer: Renderer;
 
 interface CodeSample {
@@ -147,4 +154,4 @@ declare function generateFiles({ input, output, name: nameFn, per, cwd, ...optio
 
 declare function createElement(name: string, props: object, ...child: string[]): string;
 
-export { type APIInfoProps, type Config, type GenerateOperationOutput, type GenerateOptions, type GenerateTagOutput, type MethodInformation, type ObjectCollapsibleProps, type PropertyProps, type RenderContext, type Renderer, type RequestProps, type ResponseProps, type ResponsesProps, type RouteInformation, createElement, defaultRenderer, generate, generateFiles, generateOperations, generateTags };
+export { type APIInfoProps, APIPlaygroundProps, type Config, type GenerateOperationOutput, type GenerateOptions, type GenerateTagOutput, type MethodInformation, type ObjectCollapsibleProps, type PropertyProps, type RenderContext, type Renderer, type RequestProps, type ResponseProps, type ResponsesProps, type RootProps, type RouteInformation, createElement, defaultRenderer, generate, generateFiles, generateOperations, generateTags };

package/dist/index.js

@@ -46,7 +46,7 @@ function buildOperation(method, operation) {
   };
 }
 
-// src/render/page.ts
+// src/utils/generate-document.ts
 import { dump } from "js-yaml";
 
 // src/render/element.ts
@@ -78,7 +78,7 @@ function heading(depth, child) {
 
 // src/render/renderer.ts
 var defaultRenderer = {
-  Root: (child) => createElement("Root", {}, ...child),
+  Root: (props, child) => createElement("Root", props, ...child),
   API: (child) => createElement("API", {}, ...child),
   APIInfo: (props, child) => createElement("APIInfo", props, ...child),
   APIExample: (child) => createElement("APIExample", {}, ...child),
@@ -94,11 +94,12 @@ var defaultRenderer = {
   Property: (props, child) => createElement("Property", props, ...child),
   ObjectCollapsible: (props, child) => createElement("ObjectCollapsible", props, ...child),
   Requests: (items, child) => createElement("Requests", { items }, ...child),
-  Request: ({ language, code, name }) => createElement("Request", { value: name }, codeblock({ language }, code))
+  Request: ({ language, code, name }) => createElement("Request", { value: name }, codeblock({ language }, code)),
+  APIPlayground: (props) => createElement("APIPlayground", props)
 };
 
-// src/render/page.ts
-function renderPage(title, description, content, options) {
+// src/utils/generate-document.ts
+function generateDocument(title, description, content, options) {
   const banner = dump({
     title,
     description,
@@ -108,19 +109,30 @@ function renderPage(title, description, content, options) {
   const finalImports = (options.imports ?? [
     {
       names: Object.keys(defaultRenderer),
-      from: "fumadocs-ui/components/api"
+      from: "fumadocs-openapi/ui"
     }
   ]).map(
     (item) => `import { ${item.names.join(", ")} } from ${JSON.stringify(item.from)};`
   ).join("\n");
-  const Root = options.renderer?.Root ?? defaultRenderer.Root;
   return `---
 ${banner}
 ---
 
 ${finalImports}
 
-${Root(content)}`;
+${content}`;
+}
+
+// src/utils/id-to-title.ts
+function idToTitle(id) {
+  const result = [];
+  for (const c of id) {
+    if (result.length === 0) result.push(c.toLocaleUpperCase());
+    else if (/^[A-Z]$/.test(c) && result.at(-1) !== " ") result.push(" ", c);
+    else if (c === "-") result.push(" ");
+    else result.push(c);
+  }
+  return result.join("");
 }
 
 // src/utils/schema.ts
@@ -266,6 +278,160 @@ async function getTypescriptSchema(endpoint, code) {
   }
 }
 
+// src/utils/get-security.ts
+function getScheme(requirement, document) {
+  const results = [];
+  const schemas = document.components?.securitySchemes ?? {};
+  for (const [key, scopes] of Object.entries(requirement)) {
+    if (!(key in schemas)) return [];
+    const schema = noRef(schemas[key]);
+    results.push({
+      ...schema,
+      scopes
+    });
+  }
+  return results;
+}
+
+// src/render/playground.ts
+function renderPlayground(path, method, ctx) {
+  let currentId = 0;
+  const context = {
+    schema: {},
+    nextId() {
+      return String(currentId++);
+    },
+    registered: /* @__PURE__ */ new WeakMap()
+  };
+  const body = method.requestBody ? getPreferredMedia(noRef(method.requestBody).content) : void 0;
+  return ctx.renderer.APIPlayground({
+    authorization: getAuthorizationField(method, ctx),
+    method: method.method,
+    route: path,
+    path: method.parameters.filter((v) => v.in === "path").map((v) => parameterToField(v, context)),
+    query: method.parameters.filter((v) => v.in === "query").map((v) => parameterToField(v, context)),
+    header: method.parameters.filter((v) => v.in === "header").map((v) => parameterToField(v, context)),
+    body: body?.schema ? toSchema(noRef(body.schema), true, context) : void 0,
+    schemas: context.schema
+  });
+}
+function getAuthorizationField(method, ctx) {
+  const security = method.security ?? ctx.document.security ?? [];
+  if (security.length === 0) return;
+  const singular = security.find(
+    (requirements) => Object.keys(requirements).length === 1
+  );
+  if (!singular) return;
+  const scheme = getScheme(singular, ctx.document)[0];
+  return {
+    type: "string",
+    name: "Authorization",
+    defaultValue: scheme.type === "oauth2" || scheme.type === "http" && scheme.scheme === "bearer" ? "Bearer" : "Basic",
+    isRequired: security.every(
+      (requirements) => Object.keys(requirements).length > 0
+    ),
+    description: "The Authorization access token"
+  };
+}
+function getIdFromSchema(schema, required, ctx) {
+  const registered = ctx.registered.get(schema);
+  if (registered === void 0) {
+    const id = ctx.nextId();
+    ctx.registered.set(schema, id);
+    ctx.schema[id] = toSchema(schema, required, ctx);
+    return id;
+  }
+  return registered;
+}
+function parameterToField(v, ctx) {
+  return {
+    name: v.name,
+    ...toSchema(
+      noRef(v.schema) ?? { type: "string" },
+      v.required ?? false,
+      ctx
+    )
+  };
+}
+function toReference(schema, required, ctx) {
+  return {
+    type: "ref",
+    isRequired: required,
+    schema: getIdFromSchema(schema, false, ctx)
+  };
+}
+function toSchema(schema, required, ctx) {
+  if (schema.type === "array") {
+    return {
+      type: "array",
+      description: schema.description ?? schema.title,
+      isRequired: required,
+      items: getIdFromSchema(noRef(schema.items), false, ctx)
+    };
+  }
+  if (schema.type === "object" || schema.properties !== void 0 || schema.allOf !== void 0) {
+    const properties = {};
+    Object.entries(schema.properties ?? {}).forEach(([key, prop]) => {
+      properties[key] = toReference(
+        noRef(prop),
+        schema.required?.includes(key) ?? false,
+        ctx
+      );
+    });
+    schema.allOf?.forEach((c) => {
+      const field = toSchema(noRef(c), true, ctx);
+      if (field.type === "object") Object.assign(properties, field.properties);
+    });
+    const additional = noRef(schema.additionalProperties);
+    let additionalProperties;
+    if (additional && typeof additional === "object") {
+      if (!additional.type && !additional.anyOf && !additional.allOf && !additional.oneOf) {
+        additionalProperties = true;
+      } else {
+        additionalProperties = getIdFromSchema(additional, false, ctx);
+      }
+    } else {
+      additionalProperties = additional;
+    }
+    return {
+      type: "object",
+      isRequired: required,
+      description: schema.description ?? schema.title,
+      properties,
+      additionalProperties
+    };
+  }
+  if (schema.type === void 0) {
+    const combine = schema.anyOf ?? schema.oneOf;
+    if (combine) {
+      return {
+        type: "switcher",
+        description: schema.description ?? schema.title,
+        items: Object.fromEntries(
+          combine.map((c, idx) => {
+            const item = noRef(c);
+            return [
+              item.title ?? item.type ?? `Item ${idx.toString()}`,
+              toReference(item, true, ctx)
+            ];
+          })
+        ),
+        isRequired: required
+      };
+    }
+    return {
+      type: "null",
+      isRequired: false
+    };
+  }
+  return {
+    type: schema.type === "integer" ? "number" : schema.type,
+    defaultValue: schema.example ?? "",
+    isRequired: required,
+    description: schema.description ?? schema.title
+  };
+}
+
 // src/render/schema.ts
 var keys = {
   example: "Example",
@@ -278,42 +444,46 @@ var keys = {
   format: "Format"
 };
 function isObject(schema) {
-  return schema.type === "object" || schema.properties !== void 0;
+  return schema.type === "object" || schema.properties !== void 0 || schema.additionalProperties !== void 0;
 }
 function schemaElement(name, schema, ctx) {
+  return render(name, schema, {
+    ...ctx,
+    stack: []
+  });
+}
+function render(name, schema, ctx) {
   if (schema.readOnly && !ctx.readOnly) return "";
   if (schema.writeOnly && !ctx.writeOnly) return "";
   const { renderer } = ctx.render;
   const child = [];
   function field(key, value) {
-    child.push(span(`${key}:  \`${value}\``));
+    child.push(span(`${key}: \`${value}\``));
   }
   if (isObject(schema) && ctx.parseObject) {
     const { additionalProperties, properties } = schema;
-    if (additionalProperties) {
-      if (additionalProperties === true) {
-        child.push(
-          renderer.Property(
-            {
-              name: "[key: string]",
-              type: "any"
-            },
-            []
-          )
-        );
-      } else {
-        child.push(
-          schemaElement("[key: string]", noRef(additionalProperties), {
-            ...ctx,
-            required: false,
-            parseObject: false
-          })
-        );
-      }
+    if (additionalProperties === true) {
+      child.push(
+        renderer.Property(
+          {
+            name: "[key: string]",
+            type: "any"
+          },
+          []
+        )
+      );
+    } else if (additionalProperties) {
+      child.push(
+        render("[key: string]", noRef(additionalProperties), {
+          ...ctx,
+          required: false,
+          parseObject: false
+        })
+      );
     }
     Object.entries(properties ?? {}).forEach(([key, value]) => {
       child.push(
-        schemaElement(key, noRef(value), {
+        render(key, noRef(value), {
           ...ctx,
           required: schema.required?.includes(key) ?? false,
           parseObject: false
@@ -334,17 +504,48 @@ function schemaElement(name, schema, ctx) {
       schema.enum.map((value) => JSON.stringify(value)).join(" | ")
     );
   }
-  const resolved = resolveObjectType(schema);
-  if (resolved && !ctx.parseObject) {
+  if (isObject(schema) && !ctx.parseObject) {
+    child.push(
+      renderer.ObjectCollapsible({ name }, [
+        render(name, schema, {
+          ...ctx,
+          parseObject: true,
+          required: false
+        })
+      ])
+    );
+  } else if (schema.allOf) {
     child.push(
       renderer.ObjectCollapsible({ name }, [
-        schemaElement(name, resolved, {
+        render(name, combineSchema(schema.allOf.map(noRef)), {
           ...ctx,
           parseObject: true,
           required: false
         })
       ])
     );
+  } else {
+    const mentionedObjectTypes = [
+      ...schema.anyOf ?? schema.oneOf ?? [],
+      ...schema.not ? [schema.not] : [],
+      ...schema.type === "array" ? [schema.items] : []
+    ].map(noRef).filter((s) => isComplexType(s) && !ctx.stack.includes(s));
+    ctx.stack.push(schema);
+    child.push(
+      ...mentionedObjectTypes.map(
+        (s, idx) => renderer.ObjectCollapsible(
+          { name: s.title ?? `Object ${(idx + 1).toString()}` },
+          [
+            render("element", noRef(s), {
+              ...ctx,
+              parseObject: true,
+              required: false
+            })
+          ]
+        )
+      )
+    );
+    ctx.stack.pop();
   }
   return renderer.Property(
     {
@@ -356,28 +557,51 @@ function schemaElement(name, schema, ctx) {
     child
   );
 }
-function resolveObjectType(schema) {
-  if (isObject(schema)) return schema;
-  if (schema.type === "array") {
-    return resolveObjectType(noRef(schema.items));
+function combineSchema(schema) {
+  const result = {
+    type: "object"
+  };
+  function add(s) {
+    result.properties ??= {};
+    if (s.properties) {
+      Object.assign(result.properties, s.properties);
+    }
+    result.additionalProperties ??= {};
+    if (s.additionalProperties === true) {
+      result.additionalProperties = true;
+    } else if (s.additionalProperties && typeof result.additionalProperties !== "boolean") {
+      Object.assign(result.additionalProperties, s.additionalProperties);
+    }
+    if (s.allOf) {
+      add(combineSchema(s.allOf.map(noRef)));
+    }
   }
+  schema.forEach(add);
+  return result;
+}
+function isComplexType(schema) {
+  if (schema.anyOf ?? schema.oneOf ?? schema.allOf) return true;
+  return isObject(schema) || schema.type === "array";
 }
 function getSchemaType(schema) {
   if (schema.nullable) {
-    if (!schema.type) return "null";
-    return `${getSchemaType({ ...schema, nullable: false })} | null`;
+    const type = getSchemaType({ ...schema, nullable: false });
+    return type === "unknown" ? "null" : `${type} | null`;
   }
+  if (schema.title) return schema.title;
   if (schema.type === "array")
-    return `array of ${getSchemaType(noRef(schema.items))}`;
+    return `array<${getSchemaType(noRef(schema.items))}>`;
   if (schema.oneOf)
     return schema.oneOf.map((one) => getSchemaType(noRef(one))).join(" | ");
   if (schema.allOf)
     return schema.allOf.map((one) => getSchemaType(noRef(one))).join(" & ");
-  if (schema.anyOf)
+  if (schema.not) return `not ${getSchemaType(noRef(schema.not))}`;
+  if (schema.anyOf) {
     return `Any properties in ${schema.anyOf.map((one) => getSchemaType(noRef(one))).join(", ")}`;
+  }
   if (schema.type) return schema.type;
   if (isObject(schema)) return "object";
-  throw new Error(`Cannot detect object type: ${JSON.stringify(schema)}`);
+  return "unknown";
 }
 
 // src/render/operation.ts
@@ -387,9 +611,13 @@ async function renderOperation(path, method, ctx, noTitle = false) {
   const security = method.security ?? ctx.document.security;
   const info = [];
   const example = [];
-  const title = method.summary ?? method.operationId;
-  if (title && !noTitle) {
-    info.push(heading(level, title));
+  if (!noTitle) {
+    info.push(
+      heading(
+        level,
+        method.summary ?? (method.operationId ? idToTitle(method.operationId) : path)
+      )
+    );
     level++;
   }
   if (method.description) info.push(p(method.description));
@@ -448,6 +676,7 @@ async function renderOperation(path, method, ctx, noTitle = false) {
     info.push(heading(level, group), ...parameters);
   }
   info.push(getResponseTable(method));
+  info.push(renderPlayground(path, method, ctx));
   const samples = dedupe([
     {
       label: "cURL",
@@ -492,12 +721,9 @@ function dedupe(samples) {
 }
 function getAuthSection(requirements, { document, renderer }) {
   const info = [];
-  const schemas = document.components?.securitySchemes ?? {};
   for (const requirement of requirements) {
     if (info.length > 0) info.push(`---`);
-    for (const [name, scopes] of Object.entries(requirement)) {
-      if (!(name in schemas)) continue;
-      const schema = noRef(schemas[name]);
+    for (const schema of getScheme(requirement, document)) {
       if (schema.type === "http") {
         info.push(
           renderer.Property(
@@ -524,7 +750,7 @@ function getAuthSection(requirements, { document, renderer }) {
             [
               p(schema.description),
               `In: \`header\``,
-              `Scope: \`${scopes.length > 0 ? scopes.join(", ") : "none"}\``
+              `Scope: \`${schema.scopes.length > 0 ? schema.scopes.join(", ") : "none"}\``
             ]
           )
         );
@@ -606,10 +832,10 @@ async function generate(pathOrDocument, options = {}) {
       child.push(await renderOperation(route.path, method, ctx));
     }
   }
-  return renderPage(
+  return generateDocument(
     document.info.title,
     document.info.description,
-    child,
+    ctx.renderer.Root({ baseUrl: ctx.baseUrl }, child),
     options
   );
 }
@@ -620,10 +846,12 @@ async function generateOperations(pathOrDocument, options = {}) {
   return await Promise.all(
     routes.flatMap((route) => {
       return route.methods.map(async (method) => {
-        const content = renderPage(
+        const content = generateDocument(
           method.summary ?? method.method,
           method.description,
-          [await renderOperation(route.path, method, ctx, true)],
+          ctx.renderer.Root({ baseUrl: ctx.baseUrl }, [
+            await renderOperation(route.path, method, ctx, true)
+          ]),
           options
         );
         if (!method.operationId)
@@ -651,7 +879,12 @@ async function generateTags(pathOrDocument, options = {}) {
       }
       return {
         tag,
-        content: renderPage(tag, info?.description, child, options)
+        content: generateDocument(
+          idToTitle(tag),
+          info?.description,
+          ctx.renderer.Root({ baseUrl: ctx.baseUrl }, child),
+          options
+        )
       };
     })
   );
@@ -668,8 +901,8 @@ function getContext(document, options) {
 }
 
 // src/generate-file.ts
-import { mkdir, writeFile } from "node:fs/promises";
-import { dirname, join, parse } from "node:path";
+import { mkdir, writeFile } from "fs/promises";
+import { dirname, join, parse } from "path";
 import fg from "fast-glob";
 async function generateFiles({
   input,