fumadocs-openapi 4.2.1 → 4.3.0

package/dist/chunk-N4P4W4VJ.js

@@ -0,0 +1,61 @@
+// 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 });
+}
+
+// src/ui/contexts/schema.tsx
+import { createContext as createContext2, useContext as useContext2 } from "react";
+var SchemaContext = createContext2(
+  void 0
+);
+function useSchemaContext() {
+  const ctx = useContext2(SchemaContext);
+  if (!ctx) throw new Error("Missing provider");
+  return ctx;
+}
+
+export {
+  useApiContext,
+  ApiProvider,
+  SchemaContext,
+  useSchemaContext
+};

package/dist/{chunk-55ZG37EE.js → chunk-UG2WFM5D.js}

@@ -61,69 +61,10 @@ function resolve(schema, references) {
   };
 }
 
-// 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 });
-}
-
-// src/ui/contexts/schema.tsx
-import { createContext as createContext2, useContext as useContext2 } from "react";
-var SchemaContext = createContext2(
-  void 0
-);
-function useSchemaContext() {
-  const ctx = useContext2(SchemaContext);
-  if (!ctx) throw new Error("Missing provider");
-  return ctx;
-}
-
 export {
   badgeVariants,
   getBadgeColor,
   getDefaultValue,
   getDefaultValues,
-  resolve,
-  useApiContext,
-  ApiProvider,
-  SchemaContext,
-  useSchemaContext
+  resolve
 };

package/dist/index.d.ts

@@ -106,6 +106,24 @@ interface RenderContext {
     generateCodeSamples?: (endpoint: Endpoint) => Awaitable<CodeSample[]>;
 }
 
+type DocumentContext = {
+    type: 'tag';
+    tag: OpenAPIV3.TagObject | undefined;
+    routes: RouteInformation[];
+} | {
+    type: 'operation';
+    /**
+     * information of the route
+     */
+    route: RouteInformation;
+    /**
+     * information of the method (API Endpoint)
+     */
+    endpoint: MethodInformation;
+} | {
+    type: 'file';
+    routes: RouteInformation[];
+};
 interface GenerateOptions extends Pick<RenderContext, 'generateCodeSamples' | 'generateTypeScriptSchema'> {
     /**
      * The imports of your MDX components.
@@ -121,7 +139,7 @@ interface GenerateOptions extends Pick<RenderContext, 'generateCodeSamples' | 'g
      *
      * A `full: true` property will be added by default.
      */
-    frontmatter?: (title: string, description: string | undefined) => Record<string, unknown>;
+    frontmatter?: (title: string, description: string | undefined, context: DocumentContext) => Record<string, unknown>;
     renderer?: Partial<Renderer>;
 }
 interface GenerateTagOutput {
@@ -131,6 +149,7 @@ interface GenerateTagOutput {
 interface GenerateOperationOutput {
     id: string;
     content: string;
+    route: RouteInformation;
 }
 declare function generate(pathOrDocument: string | OpenAPIV3.Document, options?: GenerateOptions): Promise<string>;
 declare function generateOperations(pathOrDocument: string | OpenAPIV3.Document, options?: GenerateOptions): Promise<GenerateOperationOutput[]>;
@@ -157,10 +176,16 @@ interface Config extends GenerateOptions {
      * Specify name for output file
      */
     name?: (type: 'file' | 'tag', name: string) => string;
+    /**
+     * Group output using folders (Only works on `operation` mode)
+     *
+     * @defaultValue false
+     */
+    groupByFolder?: boolean;
     cwd?: string;
 }
-declare function generateFiles({ input, output, name: nameFn, per, cwd, ...options }: Config): Promise<void>;
+declare function generateFiles({ input, output, name: nameFn, per, cwd, groupByFolder, ...options }: Config): Promise<void>;
 
 declare function createElement(name: string, props: object, ...child: string[]): string;
 
-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 };
+export { type APIInfoProps, APIPlaygroundProps, type Config, type DocumentContext, 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

@@ -99,12 +99,20 @@ var defaultRenderer = {
 };
 
 // src/utils/generate-document.ts
-function generateDocument(title, description, content, options) {
+function generateDocument(content, options, frontmatter) {
   const banner = dump({
-    title,
-    description,
+    title: frontmatter.title,
+    description: frontmatter.description,
     full: true,
-    ...options.frontmatter?.(title, description)
+    ...frontmatter.context.type === "operation" ? {
+      method: frontmatter.context.endpoint.method,
+      route: frontmatter.context.route.path
+    } : void 0,
+    ...options.frontmatter?.(
+      frontmatter.title,
+      frontmatter.description,
+      frontmatter.context
+    )
   }).trim();
   const finalImports = (options.imports ?? [
     {
@@ -620,13 +628,13 @@ function getSchemaType(schema, ctx) {
 }
 
 // src/render/operation.ts
-async function renderOperation(path, method, ctx, noTitle = false) {
+async function renderOperation(path, method, ctx, hasHead = true) {
   let level = 2;
   const body = noRef(method.requestBody);
   const security = method.security ?? ctx.document.security;
   const info = [];
   const example = [];
-  if (!noTitle) {
+  if (hasHead) {
     info.push(
       heading(
         level,
@@ -634,8 +642,8 @@ async function renderOperation(path, method, ctx, noTitle = false) {
       )
     );
     level++;
+    if (method.description) info.push(p(method.description));
   }
-  if (method.description) info.push(p(method.description));
   info.push(renderPlayground(path, method, ctx));
   if (security) {
     info.push(heading(level, "Authorization"));
@@ -856,10 +864,15 @@ async function generate(pathOrDocument, options = {}) {
     }
   }
   return generateDocument(
-    document.info.title,
-    document.info.description,
     ctx.renderer.Root({ baseUrl: ctx.baseUrl }, child),
-    options
+    options,
+    {
+      ...document.info,
+      context: {
+        type: "file",
+        routes
+      }
+    }
   );
 }
 async function generateOperations(pathOrDocument, options = {}) {
@@ -869,19 +882,27 @@ async function generateOperations(pathOrDocument, options = {}) {
   return await Promise.all(
     routes.flatMap((route) => {
       return route.methods.map(async (method) => {
+        if (!method.operationId)
+          throw new Error("Operation ID is required for generating docs.");
         const content = generateDocument(
-          method.summary ?? method.method,
-          method.description,
           ctx.renderer.Root({ baseUrl: ctx.baseUrl }, [
-            await renderOperation(route.path, method, ctx, true)
+            await renderOperation(route.path, method, ctx, false)
           ]),
-          options
+          options,
+          {
+            title: method.summary ?? method.method,
+            description: method.description,
+            context: {
+              type: "operation",
+              endpoint: method,
+              route
+            }
+          }
         );
-        if (!method.operationId)
-          throw new Error("Operation ID is required for generating docs.");
         return {
           id: method.operationId,
-          content
+          content,
+          route
         };
       });
     })
@@ -903,10 +924,17 @@ async function generateTags(pathOrDocument, options = {}) {
       return {
         tag,
         content: generateDocument(
-          idToTitle(tag),
-          info?.description,
           ctx.renderer.Root({ baseUrl: ctx.baseUrl }, child),
-          options
+          options,
+          {
+            title: idToTitle(tag),
+            description: info?.description,
+            context: {
+              type: "tag",
+              tag: info,
+              routes
+            }
+          }
         )
       };
     })
@@ -935,6 +963,7 @@ async function generateFiles({
   name: nameFn,
   per = "file",
   cwd = process.cwd(),
+  groupByFolder = false,
   ...options
 }) {
   const outputDir = join(cwd, output);
@@ -951,23 +980,39 @@ async function generateFiles({
         return;
       }
       if (per === "operation") {
+        const routeFolders = /* @__PURE__ */ new Set();
         const results2 = await generateOperations(path, options);
         await Promise.all(
           results2.map(async (result) => {
-            const outPath = join(
+            const outPath = groupByFolder ? join(
               outputDir,
               filename,
-              `${getName(result.id)}.mdx`
-            );
+              result.route.summary ? getFilename(result.route.summary) : getFilenameFromRoute(result.route.path),
+              `${getFilename(result.id)}.mdx`
+            ) : join(outputDir, filename, `${getFilename(result.id)}.mdx`);
+            if (groupByFolder && !routeFolders.has(dirname(outPath))) {
+              routeFolders.add(dirname(outPath));
+              if (result.route.summary) {
+                const metaFile = join(dirname(outPath), "meta.json");
+                await write(
+                  metaFile,
+                  JSON.stringify({
+                    title: result.route.summary
+                  })
+                );
+                console.log(`Generated Meta: ${metaFile}`);
+              }
+            }
             await write(outPath, result.content);
             console.log(`Generated: ${outPath}`);
           })
         );
+        return;
       }
       const results = await generateTags(path, options);
       for (const result of results) {
         let tagName = result.tag;
-        tagName = nameFn?.("tag", tagName) ?? getName(tagName);
+        tagName = nameFn?.("tag", tagName) ?? getFilename(tagName);
         const outPath = join(outputDir, filename, `${tagName}.mdx`);
         await write(outPath, result.content);
         console.log(`Generated: ${outPath}`);
@@ -975,7 +1020,10 @@ async function generateFiles({
     })
   );
 }
-function getName(s) {
+function getFilenameFromRoute(path) {
+  return path.split("/").filter((v) => !v.startsWith("{") && !v.endsWith("}")).at(-1) ?? "";
+}
+function getFilename(s) {
   return s.replace(
     /[A-Z]/g,
     (match, idx) => idx === 0 ? match : `-${match.toLowerCase()}`

package/dist/{playground-TN274MLB.js → playground-5XDMCOXX.js}

@@ -1,11 +1,13 @@
 import {
   SchemaContext,
-  getDefaultValue,
-  getDefaultValues,
-  resolve,
   useApiContext,
   useSchemaContext
-} from "./chunk-55ZG37EE.js";
+} from "./chunk-N4P4W4VJ.js";
+import {
+  getDefaultValue,
+  getDefaultValues,
+  resolve
+} from "./chunk-UG2WFM5D.js";
 
 // src/ui/playground.tsx
 import {

package/dist/source/index.d.ts

@@ -0,0 +1,10 @@
+import { BuildPageTreeOptions } from 'fumadocs-core/source';
+
+/**
+ * Source API Integration
+ *
+ * Add this to page tree builder options
+ */
+declare const attachFile: BuildPageTreeOptions['attachFile'];
+
+export { attachFile };

package/dist/source/index.js

@@ -0,0 +1,39 @@
+import {
+  getBadgeColor
+} from "../chunk-UG2WFM5D.js";
+
+// src/source/index.ts
+import React from "react";
+import { cva } from "class-variance-authority";
+var attachFile = (node, file) => {
+  if (!file) return node;
+  const data = file.data.data;
+  if ("method" in data && typeof data.method === "string") {
+    node.name = [node.name, " ", ApiIndicator({ method: data.method })];
+  }
+  return node;
+};
+var badgeVariants = cva("rounded-full border px-1.5 text-xs font-medium", {
+  variants: {
+    color: {
+      green: "bg-green-400/20 text-green-600 dark:text-green-400",
+      yellow: "bg-yellow-400/20 text-yellow-600 dark:text-yellow-400",
+      red: "bg-red-400/20 text-red-600 dark:text-red-400",
+      blue: "bg-blue-400/20 text-blue-600 dark:text-blue-400",
+      orange: "bg-orange-400/20 text-orange-600 dark:text-orange-400"
+    }
+  }
+});
+function ApiIndicator({ method }) {
+  const color = getBadgeColor(method);
+  return React.createElement(
+    "span",
+    {
+      className: badgeVariants({ className: "ms-auto", color })
+    },
+    method
+  );
+}
+export {
+  attachFile
+};

package/dist/ui/index.js

@@ -1,11 +1,13 @@
 "use client";
 import {
   ApiProvider,
-  badgeVariants,
-  getBadgeColor,
   useApiContext,
   useSchemaContext
-} from "../chunk-55ZG37EE.js";
+} from "../chunk-N4P4W4VJ.js";
+import {
+  badgeVariants,
+  getBadgeColor
+} from "../chunk-UG2WFM5D.js";
 
 // src/ui/index.ts
 import { Tab, Tabs } from "fumadocs-ui/components/tabs";
@@ -174,7 +176,7 @@ function CopyRouteButton({
 
 // src/ui/index.ts
 var APIPlayground = dynamic(
-  () => import("../playground-TN274MLB.js").then((mod) => mod.APIPlayground)
+  () => import("../playground-5XDMCOXX.js").then((mod) => mod.APIPlayground)
 );
 var Responses = Tabs;
 var Response = Tab;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fumadocs-openapi",
-  "version": "4.2.1",
+  "version": "4.3.0",
   "description": "Generate MDX docs for your OpenAPI spec",
   "keywords": [
     "NextJs",
@@ -19,6 +19,10 @@
     "./ui": {
       "import": "./dist/ui/index.js",
       "types": "./dist/ui/index.d.ts"
+    },
+    "./source": {
+      "import": "./dist/source/index.js",
+      "types": "./dist/source/index.d.ts"
     }
   },
   "main": "./dist/index.js",
@@ -30,6 +34,9 @@
       ],
       "ui": [
         "./dist/ui/index.d.ts"
+      ],
+      "source": [
+        "./dist/source/index.d.ts"
       ]
     }
   },
@@ -49,8 +56,8 @@
     "react-hook-form": "^7.52.1",
     "shiki": "^1.11.1",
     "swr": "^2.2.5",
-    "fumadocs-core": "13.0.2",
-    "fumadocs-ui": "13.0.2"
+    "fumadocs-core": "13.0.4",
+    "fumadocs-ui": "13.0.4"
   },
   "devDependencies": {
     "@types/js-yaml": "^4.0.9",