fumadocs-openapi 3.3.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,7 +444,7 @@ 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, {
@@ -348,9 +514,19 @@ function render(name, schema, ctx) {
         })
       ])
     );
+  } else if (schema.allOf) {
+    child.push(
+      renderer.ObjectCollapsible({ name }, [
+        render(name, combineSchema(schema.allOf.map(noRef)), {
+          ...ctx,
+          parseObject: true,
+          required: false
+        })
+      ])
+    );
   } else {
     const mentionedObjectTypes = [
-      ...schema.anyOf ?? schema.oneOf ?? schema.allOf ?? [],
+      ...schema.anyOf ?? schema.oneOf ?? [],
       ...schema.not ? [schema.not] : [],
       ...schema.type === "array" ? [schema.items] : []
     ].map(noRef).filter((s) => isComplexType(s) && !ctx.stack.includes(s));
@@ -381,6 +557,28 @@ function render(name, schema, ctx) {
     child
   );
 }
+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";
@@ -413,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));
@@ -474,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",
@@ -518,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(
@@ -550,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"}\``
             ]
           )
         );
@@ -632,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
   );
 }
@@ -646,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)
@@ -677,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
+        )
       };
     })
   );
@@ -694,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,

package/dist/playground-D8pYn13F.d.ts

@@ -0,0 +1,52 @@
+interface BaseRequestField {
+    name: string;
+    description?: string;
+}
+interface BaseSchema {
+    description?: string;
+    isRequired: boolean;
+}
+type PrimitiveRequestField = BaseRequestField & PrimitiveSchema;
+interface PrimitiveSchema extends BaseSchema {
+    type: 'boolean' | 'string' | 'number';
+    defaultValue: string;
+}
+interface ReferenceSchema extends BaseSchema {
+    type: 'ref';
+    schema: string;
+}
+interface ArraySchema extends BaseSchema {
+    type: 'array';
+    /**
+     * Reference to item schema or the schema
+     */
+    items: string | RequestSchema;
+}
+interface ObjectSchema extends BaseSchema {
+    type: 'object';
+    properties: Record<string, ReferenceSchema>;
+    /**
+     * Reference to schema, or true if it's `any`
+     */
+    additionalProperties?: boolean | string;
+}
+interface SwitcherSchema extends BaseSchema {
+    type: 'switcher';
+    items: Record<string, ReferenceSchema | RequestSchema>;
+}
+interface NullSchema extends BaseSchema {
+    type: 'null';
+}
+type RequestSchema = PrimitiveSchema | ArraySchema | ObjectSchema | SwitcherSchema | NullSchema;
+interface APIPlaygroundProps {
+    route: string;
+    method: string;
+    authorization?: PrimitiveRequestField;
+    path?: PrimitiveRequestField[];
+    query?: PrimitiveRequestField[];
+    header?: PrimitiveRequestField[];
+    body?: RequestSchema;
+    schemas: Record<string, RequestSchema>;
+}
+
+export type { APIPlaygroundProps as A, PrimitiveRequestField as P, RequestSchema as R, ReferenceSchema as a };