fumadocs-openapi 5.0.3 → 5.2.0

package/dist/index.d.ts

@@ -221,6 +221,7 @@ interface GenerateOptions {
      * A `full: true` property will be added by default.
      */
     frontmatter?: (title: string, description: string | undefined, context: DocumentContext) => Record<string, unknown>;
+    cwd?: string;
 }
 interface GenerateTagOutput {
     tag: string;
@@ -246,10 +247,10 @@ interface Config extends GenerateOptions {
     output: string;
     /**
      * tag: Generate a page for each tag
-     *
      * file: Generate a page for each schema
+     * operation: Generate a page for each API endpoint/operation
      *
-     * @defaultValue file
+     * @defaultValue 'operation'
      */
     per?: 'tag' | 'file' | 'operation';
     /**
@@ -269,8 +270,7 @@ interface Config extends GenerateOptions {
      * @defaultValue 'none'
      */
     groupBy?: 'tag' | 'route' | 'none';
-    cwd?: string;
 }
-declare function generateFiles({ input, output, name: nameFn, per, cwd, groupBy, ...options }: Config): Promise<void>;
+declare function generateFiles(options: Config): Promise<void>;
 
 export { type Config, type DocumentContext, type GenerateOperationOutput, type GenerateOptions, type GenerateTagOutput, type MethodInformation, type RenderContext, type RouteInformation, generateAll, generateFiles, generateOperations, generateTags };

package/dist/index.js

@@ -1,8 +1,8 @@
+import { resolve, join, parse, dirname } from 'node:path';
 import Parser from '@apidevtools/json-schema-ref-parser';
-import Slugger from 'github-slugger';
 import { dump } from 'js-yaml';
+import Slugger from 'github-slugger';
 import { mkdir, writeFile } from 'node:fs/promises';
-import { join, parse, dirname } from 'node:path';
 import fg from 'fast-glob';
 
 function createMethod(method, operation) {
@@ -55,41 +55,92 @@ const methodKeys = [
     return map;
 }
 
-function generateDocument(content, options, frontmatter) {
+function idToTitle(id) {
+    let result = [];
+    for (const c of id){
+        if (result.length === 0) result.push(c.toLocaleUpperCase());
+        else if (c === '.') result = [];
+        else if (/^[A-Z]$/.test(c) && result.at(-1) !== ' ') result.push(' ', c);
+        else if (c === '-') result.push(' ');
+        else result.push(c);
+    }
+    return result.join('');
+}
+
+function generateDocument(options) {
+    const { frontmatter } = options;
     const out = [];
+    const extend = frontmatter?.(options.title, options.description, options.context);
+    let meta;
+    if (options.context.type === 'operation') {
+        meta = {
+            method: options.context.endpoint.method,
+            route: options.context.route.path
+        };
+    }
+    const data = generateStaticData(options.dereferenced, options.page);
     const banner = dump({
-        title: frontmatter.title,
-        description: frontmatter.description,
+        title: options.title,
+        description: options.description,
         full: true,
-        ...frontmatter.context.type === 'operation' ? {
-            method: frontmatter.context.endpoint.method,
-            route: frontmatter.context.route.path
-        } : undefined,
-        ...options.frontmatter?.(frontmatter.title, frontmatter.description, frontmatter.context)
+        ...extend,
+        _openapi: {
+            ...meta,
+            ...data,
+            ...extend?._openapi
+        }
     }).trim();
     if (banner.length > 0) out.push(`---\n${banner}\n---`);
     const imports = options.imports?.map((item)=>`import { ${item.names.join(', ')} } from ${JSON.stringify(item.from)};`).join('\n');
     if (imports) {
         out.push(imports);
     }
-    out.push(content);
+    out.push(pageContent(options.page));
     return out.join('\n\n');
 }
-
-function idToTitle(id) {
-    let result = [];
-    for (const c of id){
-        if (result.length === 0) result.push(c.toLocaleUpperCase());
-        else if (c === '.') result = [];
-        else if (/^[A-Z]$/.test(c) && result.at(-1) !== ' ') result.push(' ', c);
-        else if (c === '-') result.push(' ');
-        else result.push(c);
+function generateStaticData(dereferenced, props) {
+    const slugger = new Slugger();
+    const toc = [];
+    const structuredData = {
+        headings: [],
+        contents: []
+    };
+    for (const item of props.operations){
+        const operation = dereferenced.paths[item.path]?.[item.method];
+        if (!operation) continue;
+        if (props.hasHead && operation.operationId) {
+            const title = operation.summary ?? (operation.operationId ? idToTitle(operation.operationId) : item.path);
+            const id = slugger.slug(title);
+            toc.push({
+                depth: 2,
+                title,
+                url: `#${id}`
+            });
+            structuredData.headings.push({
+                content: title,
+                id
+            });
+        }
+        if (operation.description) structuredData.contents.push({
+            content: operation.description,
+            heading: structuredData.headings.at(-1)?.id
+        });
     }
-    return result.join('');
+    return {
+        toc,
+        structuredData
+    };
+}
+function pageContent(props) {
+    return `<APIPage document={${JSON.stringify(props.document)}} operations={${JSON.stringify(props.operations)}} hasHead={${JSON.stringify(props.hasHead)}} />`;
 }
 
+async function dereference(pathOrDocument, options) {
+    return await Parser.dereference(// resolve paths
+    typeof pathOrDocument === 'string' && !pathOrDocument.startsWith('http://') && !pathOrDocument.startsWith('https://') ? resolve(options.cwd ?? process.cwd(), pathOrDocument) : pathOrDocument);
+}
 async function generateAll(pathOrDocument, options = {}) {
-    const document = await Parser.dereference(pathOrDocument);
+    const document = await dereference(pathOrDocument, options);
     const routes = buildRoutes(document).get('all') ?? [];
     const operations = [];
     for (const route of routes){
@@ -100,12 +151,16 @@ async function generateAll(pathOrDocument, options = {}) {
             });
         }
     }
-    return generateDocument(pageContent(document, {
-        operations,
-        hasHead: true
-    }), options, {
+    return generateDocument({
+        ...options,
+        dereferenced: document,
         title: document.info.title,
         description: document.info.description,
+        page: {
+            operations,
+            hasHead: true,
+            document: pathOrDocument
+        },
         context: {
             type: 'file',
             routes
@@ -113,20 +168,24 @@ async function generateAll(pathOrDocument, options = {}) {
     });
 }
 async function generateOperations(pathOrDocument, options = {}) {
-    const document = await Parser.dereference(pathOrDocument);
+    const document = await dereference(pathOrDocument, options);
     const routes = buildRoutes(document).get('all') ?? [];
     return routes.flatMap((route)=>{
         return route.methods.map((method)=>{
             if (!method.operationId) throw new Error('Operation ID is required for generating docs.');
-            const content = generateDocument(pageContent(document, {
-                operations: [
-                    {
-                        path: route.path,
-                        method: method.method.toLowerCase()
-                    }
-                ],
-                hasHead: false
-            }), options, {
+            const content = generateDocument({
+                ...options,
+                page: {
+                    operations: [
+                        {
+                            path: route.path,
+                            method: method.method.toLowerCase()
+                        }
+                    ],
+                    hasHead: false,
+                    document: pathOrDocument
+                },
+                dereferenced: document,
                 title: method.summary ?? idToTitle(method.operationId),
                 description: method.description,
                 context: {
@@ -144,7 +203,7 @@ async function generateOperations(pathOrDocument, options = {}) {
     });
 }
 async function generateTags(pathOrDocument, options = {}) {
-    const document = await Parser.dereference(pathOrDocument);
+    const document = await dereference(pathOrDocument, options);
     const tags = Array.from(buildRoutes(document).entries());
     return tags.filter(([tag])=>tag !== 'all').map(([tag, routes])=>{
         const info = document.tags?.find((t)=>t.name === tag);
@@ -159,10 +218,14 @@ async function generateTags(pathOrDocument, options = {}) {
         }
         return {
             tag,
-            content: generateDocument(pageContent(document, {
-                operations,
-                hasHead: true
-            }), options, {
+            content: generateDocument({
+                ...options,
+                page: {
+                    document: pathOrDocument,
+                    operations,
+                    hasHead: true
+                },
+                dereferenced: document,
                 title: idToTitle(tag),
                 description: info?.description,
                 context: {
@@ -174,74 +237,41 @@ async function generateTags(pathOrDocument, options = {}) {
         };
     });
 }
-function pageContent(doc, props) {
-    const slugger = new Slugger();
-    const toc = [];
-    const structuredData = {
-        headings: [],
-        contents: []
-    };
-    for (const item of props.operations){
-        const operation = doc.paths[item.path]?.[item.method];
-        if (!operation) continue;
-        if (props.hasHead && operation.operationId) {
-            const title = operation.summary ?? (operation.operationId ? idToTitle(operation.operationId) : item.path);
-            const id = slugger.slug(title);
-            toc.push({
-                depth: 2,
-                title,
-                url: `#${id}`
-            });
-            structuredData.headings.push({
-                content: title,
-                id
-            });
-        }
-        if (operation.description) structuredData.contents.push({
-            content: operation.description,
-            heading: structuredData.headings.at(-1)?.id
-        });
-    }
-    // modify toc and structured data if possible
-    // it may not be compatible with other content sources except Fumadocs MDX
-    // TODO: Maybe add to frontmatter and let developers to handle them?
-    return `<APIPage operations={${JSON.stringify(props.operations)}} hasHead={${JSON.stringify(props.hasHead)}} />
-
-export function startup() {
-    if (typeof toc !== 'undefined') {
-        // toc might be immutable
-        while (toc.length > 0) toc.pop()
-        toc.push(...${JSON.stringify(toc)})
-    }
-    
-    if (typeof structuredData !== 'undefined') {
-        structuredData.headings = ${JSON.stringify(structuredData.headings)}
-        structuredData.contents = ${JSON.stringify(structuredData.contents)}
-    }
-}
 
-{startup()}`;
-}
-
-async function generateFiles({ input, output, name: nameFn, per = 'file', cwd = process.cwd(), groupBy = 'none', ...options }) {
+async function generateFiles(options) {
+    const { input, output, name: nameFn, per = 'operation', groupBy = 'none', cwd = process.cwd() } = options;
     const outputDir = join(cwd, output);
-    const resolvedInputs = await fg.glob(input, {
-        absolute: true,
-        cwd
-    });
-    await Promise.all(resolvedInputs.map(async (path)=>{
+    const urlInputs = [];
+    const fileInputs = [];
+    for (const v of typeof input === 'string' ? [
+        input
+    ] : input){
+        if (isUrl(v)) {
+            urlInputs.push(v);
+        } else {
+            fileInputs.push(v);
+        }
+    }
+    const resolvedInputs = [
+        ...await fg.glob(fileInputs, {
+            cwd,
+            absolute: false
+        }),
+        ...urlInputs
+    ];
+    await Promise.all(resolvedInputs.map(async (pathOrUrl)=>{
         if (per === 'file') {
-            let filename = parse(path).name;
+            let filename = isUrl(pathOrUrl) ? 'index' : parse(pathOrUrl).name;
             if (nameFn) filename = nameFn('file', filename);
             const outPath = join(outputDir, `${filename}.mdx`);
-            const result = await generateAll(path, options);
+            const result = await generateAll(pathOrUrl, options);
             await write(outPath, result);
             console.log(`Generated: ${outPath}`);
             return;
         }
         if (per === 'operation') {
             const metaFiles = new Set();
-            const results = await generateOperations(path, options);
+            const results = await generateOperations(pathOrUrl, options);
             await Promise.all(results.map(async (result)=>{
                 let outPath;
                 if (!result.method.operationId) return;
@@ -267,7 +297,7 @@ async function generateFiles({ input, output, name: nameFn, per = 'file', cwd =
             }));
             return;
         }
-        const results = await generateTags(path, options);
+        const results = await generateTags(pathOrUrl, options);
         for (const result of results){
             let tagName = result.tag;
             tagName = nameFn?.('tag', tagName) ?? getFilename(tagName);
@@ -277,6 +307,9 @@ async function generateFiles({ input, output, name: nameFn, per = 'file', cwd =
         }
     }));
 }
+function isUrl(input) {
+    return input.startsWith('https://') || input.startsWith('http://');
+}
 function getFilenameFromRoute(path) {
     return path.replaceAll('.', '/').split('/').filter((v)=>!v.startsWith('{') && !v.endsWith('}')).at(-1) ?? '';
 }

package/dist/server/index.d.ts

@@ -181,25 +181,29 @@ interface RenderContext {
 }
 
 interface ApiPageProps extends Pick<RenderContext, 'generateCodeSamples' | 'generateTypeScriptSchema'> {
-    document: OpenAPIV3.Document;
+    document: string | OpenAPIV3.Document;
     /**
-     * An array of operation
+     * An array of operations
      */
-    operations: {
-        path: string;
-        method: OpenAPIV3.HttpMethods;
-    }[];
+    operations: Operation[];
     hasHead: boolean;
     renderer?: Partial<Renderer>;
 }
+interface Operation {
+    path: string;
+    method: OpenAPIV3.HttpMethods;
+}
 
 interface OpenAPIOptions extends Omit<Partial<ApiPageProps>, 'document'> {
-    documentOrPath: string | OpenAPIV3.Document;
+    /**
+     * @deprecated Pass document to `APIPage` instead
+     */
+    documentOrPath?: string | OpenAPIV3.Document;
 }
 interface OpenAPIServer {
-    APIPage: FC<Omit<ApiPageProps, 'document'>>;
+    APIPage: FC<ApiPageProps>;
 }
-declare function createOpenAPI(options: OpenAPIOptions): OpenAPIServer;
+declare function createOpenAPI(options?: OpenAPIOptions): OpenAPIServer;
 
 /**
  * Source API Integration

package/dist/server/index.js

@@ -1,6 +1,6 @@
 import { jsx, jsxs, Fragment as Fragment$1 } from 'react/jsx-runtime';
-import Parser from '@apidevtools/json-schema-ref-parser';
 import Slugger from 'github-slugger';
+import Parser from '@apidevtools/json-schema-ref-parser';
 import { createElement, Fragment, useMemo } from 'react';
 import { sample } from 'openapi-sampler';
 import { compile } from 'json-schema-to-typescript';
@@ -1001,8 +1001,17 @@ const defaultRenderer = {
     APIPlayground
 };
 
-function APIPage(props) {
-    const { operations, document, hasHead = true } = props;
+const cache = new Map();
+async function APIPage(props) {
+    const { operations, hasHead = true } = props;
+    let document;
+    if (typeof props.document === 'string') {
+        const cached = cache.get(props.document);
+        document = cached ?? await Parser.dereference(props.document);
+        cache.set(props.document, document);
+    } else {
+        document = await Parser.dereference(props.document);
+    }
     const ctx = getContext(document, props);
     return /*#__PURE__*/ jsx(ctx.renderer.Root, {
         baseUrl: ctx.baseUrl,
@@ -1033,12 +1042,11 @@ function getContext(document, options) {
     };
 }
 
-function createOpenAPI(options) {
-    const document = Parser.dereference(options.documentOrPath);
+function createOpenAPI(options = {}) {
     return {
-        APIPage: async (props)=>{
+        APIPage (props) {
             return /*#__PURE__*/ jsx(APIPage, {
-                document: await document,
+                ...options,
                 ...props
             });
         }
@@ -1078,8 +1086,13 @@ function getBadgeColor(method) {
  */ const attachFile = (node, file)=>{
     if (!file) return node;
     const data = file.data.data;
-    if ('method' in data && typeof data.method === 'string') {
-        const color = getBadgeColor(data.method);
+    let method;
+    if ('_openapi' in data && typeof data._openapi === 'object') {
+        const meta = data._openapi;
+        method = meta.method;
+    }
+    if (method) {
+        const color = getBadgeColor(method);
         node.name = /*#__PURE__*/ jsxs(Fragment$1, {
             children: [
                 node.name,
@@ -1089,7 +1102,7 @@ function getBadgeColor(method) {
                         className: 'ms-auto text-nowrap',
                         color
                     }),
-                    children: data.method
+                    children: method
                 })
             ]
         });

package/dist/ui/{client-client-BIwAR59x.js → client-client-34yX5eij.js}

@@ -64,7 +64,7 @@ function useSchemaContext() {
     return ctx;
 }
 
-const APIPlayground = dynamic(()=>import('./playground-client-CjCikhf6.js').then((mod)=>mod.APIPlayground));
+const APIPlayground = dynamic(()=>import('./playground-client-itvkUjgt.js').then((mod)=>mod.APIPlayground));
 function Root({ children, baseUrl, className, ...props }) {
     return /*#__PURE__*/ jsx("div", {
         className: cn('flex flex-col gap-24 text-sm text-fd-muted-foreground', className),
@@ -87,6 +87,7 @@ function CopyRouteButton({ className, route, ...props }) {
             className
         })),
         onClick: onCopy,
+        "aria-label": "Copy route path",
         ...props,
         children: checked ? /*#__PURE__*/ jsx(Check, {
             className: "size-3"

package/dist/ui/index.js

@@ -3,8 +3,8 @@ import { cn } from 'fumadocs-ui/components/api';
 import { Fragment } from 'react';
 import { Accordions, Accordion } from 'fumadocs-ui/components/accordion';
 import { cva } from 'class-variance-authority';
-import { C as CopyRouteButton } from './client-client-BIwAR59x.js';
-export { A as APIPlayground, R as Root, u as useSchemaContext } from './client-client-BIwAR59x.js';
+import { C as CopyRouteButton } from './client-client-34yX5eij.js';
+export { A as APIPlayground, R as Root, u as useSchemaContext } from './client-client-34yX5eij.js';
 
 const badgeVariants = cva('rounded border px-1.5 py-1 text-xs font-medium leading-[12px]', {
     variants: {

package/dist/ui/{playground-client-CjCikhf6.js → playground-client-itvkUjgt.js}

@@ -6,7 +6,7 @@ import { FormProvider, Controller, useFormContext, useFieldArray, useForm, useWa
 import useSWRImmutable from 'swr/immutable';
 import { Accordions, Accordion } from 'fumadocs-ui/components/accordion';
 import { cn, buttonVariants } from 'fumadocs-ui/components/api';
-import { u as useSchemaContext, a as useApiContext, S as SchemaContext } from './client-client-BIwAR59x.js';
+import { u as useSchemaContext, a as useApiContext, S as SchemaContext } from './client-client-34yX5eij.js';
 import { Slot } from '@radix-ui/react-slot';
 import { cva } from 'class-variance-authority';
 import { CircleCheckIcon, CircleXIcon, ChevronDown, ChevronUp, Check, Trash2, Plus } from 'lucide-react';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fumadocs-openapi",
-  "version": "5.0.3",
+  "version": "5.2.0",
   "description": "Generate MDX docs for your OpenAPI spec",
   "keywords": [
     "NextJs",
@@ -44,7 +44,7 @@
     "dist"
   ],
   "dependencies": {
-    "@apidevtools/json-schema-ref-parser": "^11.6.4",
+    "@apidevtools/json-schema-ref-parser": "^11.7.0",
     "@mdx-js/mdx": "^3.0.1",
     "@radix-ui/react-select": "^2.1.1",
     "@radix-ui/react-slot": "^1.1.0",
@@ -54,21 +54,21 @@
     "github-slugger": "^2.0.0",
     "js-yaml": "^4.1.0",
     "json-schema-to-typescript": "^15.0.0",
-    "lucide-react": "^0.414.0",
+    "lucide-react": "^0.427.0",
     "openapi-sampler": "^1.5.1",
-    "react-hook-form": "^7.52.1",
+    "react-hook-form": "^7.52.2",
     "remark": "^15.0.0",
-    "shiki": "^1.11.1",
+    "shiki": "^1.12.1",
     "swr": "^2.2.5",
-    "fumadocs-core": "13.2.0",
-    "fumadocs-ui": "13.2.0"
+    "fumadocs-core": "13.2.2",
+    "fumadocs-ui": "13.2.2"
   },
   "devDependencies": {
     "@types/js-yaml": "^4.0.9",
     "@types/node": "20.14.12",
     "@types/openapi-sampler": "^1.0.3",
     "@types/react": "^18.3.3",
-    "bunchee": "^5.3.1",
+    "bunchee": "^5.3.2",
     "next": "^14.2.5",
     "openapi-types": "^12.1.3",
     "eslint-config-custom": "0.0.0",