fumadocs-openapi 9.2.3 → 9.3.1

package/dist/generate-file.d.ts

@@ -8,6 +8,10 @@ interface GenerateFileOutput {
     pathOrUrl: string;
     content: string;
 }
+export interface OutputFile {
+    path: string;
+    content: string;
+}
 interface OperationConfig extends BaseConfig {
     /**
      * Generate a page for each API endpoint/operation (default).
@@ -59,6 +63,22 @@ interface BaseName {
      */
     algorithm?: 'v2' | 'v1';
 }
+interface IndexItem {
+    path: string;
+    title?: string;
+    description?: string;
+    /**
+     * Specify linked pages:
+     * - items in `inputs` to include all generated pages of a specific schema.
+     * - specific Markdown/MDX files.
+     */
+    only?: (string | OutputFile)[];
+}
+interface HookContext {
+    files: OutputFile[];
+    readonly generated: Record<string, OutputFile[]>;
+    readonly documents: Record<string, ProcessedDocument>;
+}
 interface BaseConfig extends GenerateOptions {
     /**
      * Schema files, or the OpenAPI server object
@@ -74,7 +94,28 @@ interface BaseConfig extends GenerateOptions {
      * By default, it only escapes whitespaces and upper case (English) characters
      */
     slugify?: (name: string) => string;
+    /**
+     * Generate index files with cards linking to generated pages.
+     */
+    index?: {
+        items: IndexItem[] | ((ctx: HookContext) => IndexItem[]);
+        /**
+         * Generate URLs for cards
+         */
+        url: ((filePath: string) => string) | {
+            baseUrl: string;
+            /**
+             * Base content directory
+             */
+            contentDir: string;
+        };
+    };
+    /**
+     * Can add/change/remove output files before writing to file system
+     **/
+    beforeWrite?: (this: HookContext, files: OutputFile[]) => void | Promise<void>;
 }
 export declare function generateFiles(options: Config): Promise<void>;
+export declare function generateFilesOnly(options: Config): Promise<OutputFile[]>;
 export {};
 //# sourceMappingURL=generate-file.d.ts.map

package/dist/generate-file.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generate-file.d.ts","sourceRoot":"","sources":["../src/generate-file.ts"],"names":[],"mappings":"AAGA,OAAO,EAEL,KAAK,eAAe,EACpB,KAAK,kBAAkB,EAEvB,KAAK,iBAAiB,EAEvB,MAAM,YAAY,CAAC;AACpB,OAAO,EAEL,KAAK,iBAAiB,EACvB,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAE9C,UAAU,kBAAkB;IAC1B;;OAEG;IACH,SAAS,EAAE,MAAM,CAAC;IAElB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,UAAU,eAAgB,SAAQ,UAAU;IAC1C;;OAEG;IACH,GAAG,CAAC,EAAE,WAAW,CAAC;IAElB;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,KAAK,GAAG,OAAO,GAAG,MAAM,CAAC;IAEnC;;OAEG;IACH,IAAI,CAAC,EACD,CAAC,CACC,MAAM,EAAE,kBAAkB,EAC1B,QAAQ,EAAE,iBAAiB,CAAC,UAAU,CAAC,KACpC,MAAM,CAAC,GACZ,QAAQ,CAAC;CACd;AAED,UAAU,SAAU,SAAQ,UAAU;IACpC;;OAEG;IACH,GAAG,EAAE,KAAK,CAAC;IAEX;;OAEG;IACH,IAAI,CAAC,EACD,CAAC,CACC,MAAM,EAAE,iBAAiB,EACzB,QAAQ,EAAE,iBAAiB,CAAC,UAAU,CAAC,KACpC,MAAM,CAAC,GACZ,QAAQ,CAAC;CACd;AAED,UAAU,UAAW,SAAQ,UAAU;IACrC;;OAEG;IACH,GAAG,EAAE,MAAM,CAAC;IAEZ;;OAEG;IACH,IAAI,CAAC,EACD,CAAC,CACC,MAAM,EAAE,kBAAkB,EAC1B,QAAQ,EAAE,iBAAiB,CAAC,UAAU,CAAC,KACpC,MAAM,CAAC,GACZ,QAAQ,CAAC;CACd;AAED,MAAM,MAAM,MAAM,GAAG,UAAU,GAAG,SAAS,GAAG,eAAe,CAAC;AAE9D,UAAU,QAAQ;IAChB;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;CACzB;AAED,UAAU,UAAW,SAAQ,eAAe;IAC1C;;OAEG;IACH,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,GAAG,aAAa,CAAC;IAEzC;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf;;;;OAIG;IACH,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;CACpC;AAED,wBAAsB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAqClE"}
+{"version":3,"file":"generate-file.d.ts","sourceRoot":"","sources":["../src/generate-file.ts"],"names":[],"mappings":"AAGA,OAAO,EAGL,KAAK,eAAe,EACpB,KAAK,kBAAkB,EAEvB,KAAK,iBAAiB,EAEvB,MAAM,YAAY,CAAC;AACpB,OAAO,EAEL,KAAK,iBAAiB,EACvB,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAI9C,UAAU,kBAAkB;IAC1B;;OAEG;IACH,SAAS,EAAE,MAAM,CAAC;IAElB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,UAAU,eAAgB,SAAQ,UAAU;IAC1C;;OAEG;IACH,GAAG,CAAC,EAAE,WAAW,CAAC;IAElB;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,KAAK,GAAG,OAAO,GAAG,MAAM,CAAC;IAEnC;;OAEG;IACH,IAAI,CAAC,EACD,CAAC,CACC,MAAM,EAAE,kBAAkB,EAC1B,QAAQ,EAAE,iBAAiB,CAAC,UAAU,CAAC,KACpC,MAAM,CAAC,GACZ,QAAQ,CAAC;CACd;AAED,UAAU,SAAU,SAAQ,UAAU;IACpC;;OAEG;IACH,GAAG,EAAE,KAAK,CAAC;IAEX;;OAEG;IACH,IAAI,CAAC,EACD,CAAC,CACC,MAAM,EAAE,iBAAiB,EACzB,QAAQ,EAAE,iBAAiB,CAAC,UAAU,CAAC,KACpC,MAAM,CAAC,GACZ,QAAQ,CAAC;CACd;AAED,UAAU,UAAW,SAAQ,UAAU;IACrC;;OAEG;IACH,GAAG,EAAE,MAAM,CAAC;IAEZ;;OAEG;IACH,IAAI,CAAC,EACD,CAAC,CACC,MAAM,EAAE,kBAAkB,EAC1B,QAAQ,EAAE,iBAAiB,CAAC,UAAU,CAAC,KACpC,MAAM,CAAC,GACZ,QAAQ,CAAC;CACd;AAED,MAAM,MAAM,MAAM,GAAG,UAAU,GAAG,SAAS,GAAG,eAAe,CAAC;AAE9D,UAAU,QAAQ;IAChB;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;CACzB;AAED,UAAU,SAAS;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;;OAIG;IACH,IAAI,CAAC,EAAE,CAAC,MAAM,GAAG,UAAU,CAAC,EAAE,CAAC;CAChC;AAED,UAAU,WAAW;IACnB,KAAK,EAAE,UAAU,EAAE,CAAC;IACpB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,EAAE,CAAC,CAAC;IACjD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;CACvD;AAED,UAAU,UAAW,SAAQ,eAAe;IAC1C;;OAEG;IACH,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,GAAG,aAAa,CAAC;IAEzC;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf;;;;OAIG;IACH,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;IAEnC;;OAEG;IACH,KAAK,CAAC,EAAE;QACN,KAAK,EAAE,SAAS,EAAE,GAAG,CAAC,CAAC,GAAG,EAAE,WAAW,KAAK,SAAS,EAAE,CAAC,CAAC;QAEzD;;WAEG;QACH,GAAG,EACC,CAAC,CAAC,QAAQ,EAAE,MAAM,KAAK,MAAM,CAAC,GAC9B;YACE,OAAO,EAAE,MAAM,CAAC;YAChB;;eAEG;YACH,UAAU,EAAE,MAAM,CAAC;SACpB,CAAC;KACP,CAAC;IAEF;;QAEI;IACJ,WAAW,CAAC,EAAE,CACZ,IAAI,EAAE,WAAW,EACjB,KAAK,EAAE,UAAU,EAAE,KAChB,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3B;AAED,wBAAsB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAUlE;AAED,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,UAAU,EAAE,CAAC,CA2DvB"}

package/dist/generate-file.js

@@ -1,87 +1,93 @@
 import { mkdir, writeFile } from 'node:fs/promises';
 import * as path from 'node:path';
 import { glob } from 'tinyglobby';
-import { generateAll, generatePages, generateTags, } from './generate.js';
-import { processDocument, } from './utils/process-document.js';
+import { generateAll, generateDocument, generatePages, generateTags, } from './generate.js';
+import { processDocumentCached, } from './utils/process-document.js';
+import { createGetUrl, getSlugs } from 'fumadocs-core/source';
+import matter from 'gray-matter';
 export async function generateFiles(options) {
-    const { cwd = process.cwd() } = options;
+    const files = await generateFilesOnly(options);
+    await Promise.all(files.map(async (file) => {
+        await mkdir(path.dirname(file.path), { recursive: true });
+        await writeFile(file.path, file.content);
+        console.log(`Generated: ${file.path}`);
+    }));
+}
+export async function generateFilesOnly(options) {
+    const { cwd = process.cwd(), beforeWrite } = options;
     const input = typeof options.input === 'string' ? [options.input] : options.input;
     let schemas = {};
-    if (Array.isArray(input)) {
-        const targets = [];
-        const patterns = [];
-        for (const item of input) {
-            if (isUrl(item))
-                targets.push(item);
-            else
-                patterns.push(item);
+    async function resolveInput(item) {
+        if (isUrl(item)) {
+            schemas[item] = await processDocumentCached(item);
+            return;
+        }
+        const resolved = await glob(item, { cwd, absolute: true });
+        if (resolved.length > 1) {
+            console.warn('glob patterns in `input` are deprecated, please specify your schemas explicitly.');
+            for (let i = 0; i < resolved.length; i++) {
+                schemas[`${item}[${i}]`] = await processDocumentCached(item);
+            }
+        }
+        else if (resolved.length === 1) {
+            schemas[item] = await processDocumentCached(resolved[0]);
         }
-        if (patterns.length > 0)
-            targets.push(...(await glob(patterns, { cwd })));
-        await Promise.all(targets.map(async (item) => {
-            schemas[item] = await processDocument(path.join(cwd, item));
-        }));
+        else {
+            throw new Error(`input not found: ${item}`);
+        }
+    }
+    if (Array.isArray(input)) {
+        await Promise.all(input.map(resolveInput));
     }
     else {
         schemas = await input.getSchemas();
     }
-    const resolvedSchemas = Object.entries(schemas);
-    if (resolvedSchemas.length === 0) {
+    const generated = {};
+    const files = [];
+    const entries = Object.entries(schemas);
+    if (entries.length === 0) {
         throw new Error('No input files found.');
     }
-    await Promise.all(resolvedSchemas.map(([id, document]) => generateFromDocument(id, document, options)));
+    for (const [id, schema] of entries) {
+        const result = generateFromDocument(id, schema, options);
+        files.push(...result);
+        generated[id] = result;
+    }
+    const context = {
+        files,
+        generated,
+        documents: schemas,
+    };
+    if (options.index) {
+        writeIndexFiles(context, options);
+    }
+    await beforeWrite?.call(context, context.files);
+    return context.files;
 }
-async function generateFromDocument(schemaId, document, options) {
+function generateFromDocument(schemaId, processed, options) {
+    const files = [];
+    const { document } = processed;
     const { output, cwd = process.cwd(), slugify = defaultSlugify } = options;
     const outputDir = path.join(cwd, output);
     let nameFn;
     if (!options.name || typeof options.name !== 'function') {
-        const { algorithm = 'v2' } = options.name ?? {};
-        nameFn = (output, document) => {
-            if (options.per === 'tag') {
-                const result = output;
-                return slugify(result.tag);
-            }
-            if (options.per === 'file') {
-                return isUrl(schemaId)
-                    ? 'index'
-                    : path.basename(schemaId, path.extname(schemaId));
-            }
-            const result = output;
-            if (result.type === 'operation') {
-                const operation = document.paths[result.item.path][result.item.method];
-                if (algorithm === 'v2' && operation.operationId) {
-                    return operation.operationId;
-                }
-                return path.join(getOutputPathFromRoute(result.item.path), result.item.method.toLowerCase());
-            }
-            const hook = document.webhooks[result.item.name][result.item.method];
-            if (algorithm === 'v2' && hook.operationId) {
-                return hook.operationId;
-            }
-            return slugify(result.item.name);
-        };
+        const algorithm = options.name?.algorithm;
+        nameFn = (out, doc) => defaultNameFn(schemaId, out, doc, options, algorithm);
     }
     else {
         nameFn = options.name;
     }
-    async function write(file, content) {
-        await mkdir(path.dirname(file), { recursive: true });
-        await writeFile(file, content);
-    }
     function getOutputPaths(groupBy = 'none', result) {
         if (groupBy === 'route') {
             return [
                 path.join(getOutputPathFromRoute(result.type === 'operation' ? result.item.path : result.item.name), `${result.item.method.toLowerCase()}.mdx`),
             ];
         }
-        const file = nameFn(result, document.document);
+        const file = nameFn(result, document);
         if (groupBy === 'tag') {
             let tags = result.type === 'operation'
-                ? document.document.paths[result.item.path][result.item.method]
-                    .tags
-                : document.document.webhooks[result.item.name][result.item.method]
-                    .tags;
+                ? document.paths[result.item.path][result.item.method].tags
+                : document.webhooks[result.item.name][result.item.method].tags;
             if (!tags || tags.length === 0) {
                 console.warn('When `groupBy` is set to `tag`, make sure a `tags` is defined for every operation schema.');
                 tags = ['unknown'];
@@ -91,46 +97,76 @@ async function generateFromDocument(schemaId, document, options) {
         return [`${file}.mdx`];
     }
     if (options.per === 'file') {
-        const result = await generateAll(schemaId, document, options);
+        const result = generateAll(schemaId, processed, options);
         const filename = nameFn({
             pathOrUrl: schemaId,
             content: result,
-        }, document.document);
-        const outPath = path.join(outputDir, `${filename}.mdx`);
-        await write(outPath, result);
-        console.log(`Generated: ${outPath}`);
+        }, document);
+        files.push({
+            path: path.join(outputDir, `${filename}.mdx`),
+            content: result,
+        });
+        return files;
     }
-    else if (options.per === 'tag') {
-        const results = await generateTags(schemaId, document, options);
+    if (options.per === 'tag') {
+        const results = generateTags(schemaId, processed, options);
         for (const result of results) {
-            const filename = nameFn(result, document.document);
-            const outPath = path.join(outputDir, `${filename}.mdx`);
-            await write(outPath, result.content);
-            console.log(`Generated: ${outPath}`);
+            const filename = nameFn(result, document);
+            files.push({
+                path: path.join(outputDir, `${filename}.mdx`),
+                content: result.content,
+            });
         }
+        return files;
     }
-    else {
-        const results = await generatePages(schemaId, document, options);
-        const mapping = new Map();
-        for (const result of results) {
-            for (const outputPath of getOutputPaths(options.groupBy, result)) {
-                mapping.set(outputPath, result);
-            }
+    const results = generatePages(schemaId, processed, options);
+    const mapping = new Map();
+    for (const result of results) {
+        for (const outputPath of getOutputPaths(options.groupBy, result)) {
+            mapping.set(outputPath, result);
         }
-        for (const [key, output] of mapping.entries()) {
-            let outputPath = key;
-            // v1 will remove nested directories
-            if (typeof options.name === 'object' && options.name.algorithm === 'v1') {
-                const isSharedDir = Array.from(mapping.keys()).some((item) => item !== outputPath &&
-                    path.dirname(item) === path.dirname(outputPath));
-                if (!isSharedDir && path.dirname(outputPath) !== '.') {
-                    outputPath = path.join(path.dirname(outputPath) + '.mdx');
-                }
+    }
+    for (const [key, output] of mapping.entries()) {
+        let outputPath = key;
+        // v1 will remove nested directories
+        if (typeof options.name === 'object' && options.name.algorithm === 'v1') {
+            const isSharedDir = Array.from(mapping.keys()).some((item) => item !== outputPath &&
+                path.dirname(item) === path.dirname(outputPath));
+            if (!isSharedDir && path.dirname(outputPath) !== '.') {
+                outputPath = path.join(path.dirname(outputPath) + '.mdx');
             }
-            await write(path.join(outputDir, outputPath), output.content);
-            console.log(`Generated: ${outputPath}`);
         }
+        files.push({
+            path: path.join(outputDir, outputPath),
+            content: output.content,
+        });
+    }
+    return files;
+}
+function defaultNameFn(schemaId, output, document, options, algorithm = 'v2') {
+    const { slugify = defaultSlugify } = options;
+    if (options.per === 'tag') {
+        const result = output;
+        return slugify(result.tag);
+    }
+    if (options.per === 'file') {
+        return isUrl(schemaId)
+            ? 'index'
+            : path.basename(schemaId, path.extname(schemaId));
+    }
+    const result = output;
+    if (result.type === 'operation') {
+        const operation = document.paths[result.item.path][result.item.method];
+        if (algorithm === 'v2' && operation.operationId) {
+            return operation.operationId;
+        }
+        return path.join(getOutputPathFromRoute(result.item.path), result.item.method.toLowerCase());
+    }
+    const hook = document.webhooks[result.item.name][result.item.method];
+    if (algorithm === 'v2' && hook.operationId) {
+        return hook.operationId;
     }
+    return slugify(result.item.name);
 }
 function isUrl(input) {
     return input.startsWith('https://') || input.startsWith('http://');
@@ -147,6 +183,62 @@ function getOutputPathFromRoute(path) {
     })
         .join('/') ?? '');
 }
+function writeIndexFiles(context, options) {
+    const { index, output, cwd = process.cwd() } = options;
+    if (!index)
+        return;
+    const { items, url } = index;
+    let urlFn;
+    if (typeof url === 'object') {
+        const getUrl = createGetUrl(url.baseUrl);
+        const contentDir = path.resolve(cwd, url.contentDir);
+        urlFn = (file) => getUrl(getSlugs(path.relative(contentDir, file)));
+    }
+    else {
+        urlFn = url;
+    }
+    function fileContent(index) {
+        const generatedPages = context.generated;
+        const content = [];
+        content.push('<Cards>');
+        const files = new Map();
+        const only = index.only ?? Object.keys(context.generated);
+        for (const item of only) {
+            if (typeof item === 'object') {
+                files.set(item.path, item);
+                continue;
+            }
+            const result = generatedPages[item];
+            if (!result)
+                throw new Error(`${item} does not exist on "input", available: ${Object.keys(generatedPages).join(', ')}.`);
+            for (const file of result) {
+                files.set(file.path, file);
+            }
+        }
+        for (const file of files.values()) {
+            const isContent = file.path.endsWith('.mdx') || file.path.endsWith('.md');
+            if (!isContent)
+                continue;
+            const { data } = matter(file.content);
+            if (typeof data.title !== 'string')
+                continue;
+            content.push(`<Card href="${urlFn(file.path)}" title=${JSON.stringify(data.title)} description=${JSON.stringify(data.description)} />`);
+        }
+        content.push('</Cards>');
+        return generateDocument({
+            title: index.title ?? 'Overview',
+            description: index.description,
+        }, content.join('\n'), options);
+    }
+    const outputDir = path.join(cwd, output);
+    for (const item of typeof items === 'function' ? items(context) : items) {
+        const outPath = path.join(outputDir, path.extname(item.path).length === 0 ? `${item.path}.mdx` : item.path);
+        context.files.push({
+            path: outPath,
+            content: fileContent(item),
+        });
+    }
+}
 function defaultSlugify(s) {
     return s.replace(/\s+/g, '-').toLowerCase();
 }

package/dist/generate.d.ts

@@ -1,6 +1,6 @@
-import { type DocumentContext } from './utils/generate-document.js';
 import type { OperationItem, WebhookItem } from './render/api-page.js';
 import type { ProcessedDocument } from './utils/process-document.js';
+import type { TagObject } from './types.js';
 export interface GenerateOptions {
     /**
      * Additional imports of your MDX components.
@@ -54,7 +54,16 @@ export type GeneratePageOutput = {
     item: WebhookItem;
     content: string;
 };
-export declare function generateAll(schemaId: string, processed: ProcessedDocument, options?: GenerateOptions): Promise<string>;
-export declare function generatePages(schemaId: string, processed: ProcessedDocument, options?: GenerateOptions): Promise<GeneratePageOutput[]>;
-export declare function generateTags(schemaId: string, processed: ProcessedDocument, options?: GenerateOptions): Promise<GenerateTagOutput[]>;
+export declare function generateAll(schemaId: string, processed: ProcessedDocument, options?: GenerateOptions): string;
+export declare function generatePages(schemaId: string, processed: ProcessedDocument, options?: GenerateOptions): GeneratePageOutput[];
+export declare function generateTags(schemaId: string, processed: ProcessedDocument, options?: GenerateOptions): GenerateTagOutput[];
+export declare function generateDocument(frontmatter: unknown, content: string, options: Pick<GenerateOptions, 'addGeneratedComment' | 'imports'>): string;
+export type DocumentContext = {
+    type: 'tag';
+    tag: TagObject | undefined;
+} | {
+    type: 'operation';
+} | {
+    type: 'file';
+};
 //# sourceMappingURL=generate.d.ts.map

package/dist/generate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generate.d.ts","sourceRoot":"","sources":["../src/generate.ts"],"names":[],"mappings":"AACA,OAAO,EACL,KAAK,eAAe,EAErB,MAAM,2BAA2B,CAAC;AAEnC,OAAO,KAAK,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACpE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAElE,MAAM,WAAW,eAAe;IAC9B;;OAEG;IACH,OAAO,CAAC,EAAE;QACR,KAAK,EAAE,MAAM,EAAE,CAAC;QAChB,IAAI,EAAE,MAAM,CAAC;KACd,EAAE,CAAC;IAEJ;;;;OAIG;IACH,WAAW,CAAC,EAAE,CACZ,KAAK,EAAE,MAAM,EACb,WAAW,EAAE,MAAM,GAAG,SAAS,EAC/B,OAAO,EAAE,eAAe,KACrB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAE7B;;;;;;OAMG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAE7B;;;;;;;OAOG;IACH,mBAAmB,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IAEvC,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb;;;;;OAKG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,iBAAiB;IAChC,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,MAAM,kBAAkB,GAC1B;IACE,IAAI,EAAE,WAAW,CAAC;IAClB,IAAI,EAAE,aAAa,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;CACjB,GACD;IACE,IAAI,EAAE,SAAS,CAAC;IAChB,IAAI,EAAE,WAAW,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAEN,wBAAsB,WAAW,CAC/B,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,iBAAiB,EAC5B,OAAO,GAAE,eAAoB,GAC5B,OAAO,CAAC,MAAM,CAAC,CAqBjB;AAED,wBAAsB,aAAa,CACjC,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,iBAAiB,EAC5B,OAAO,GAAE,eAAoB,GAC5B,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAiE/B;AAED,wBAAsB,YAAY,CAChC,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,iBAAiB,EAC5B,OAAO,GAAE,eAAoB,GAC5B,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAwC9B"}
+{"version":3,"file":"generate.d.ts","sourceRoot":"","sources":["../src/generate.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAEV,aAAa,EACb,WAAW,EACZ,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAGlE,OAAO,KAAK,EAAY,SAAS,EAAE,MAAM,SAAS,CAAC;AAKnD,MAAM,WAAW,eAAe;IAC9B;;OAEG;IACH,OAAO,CAAC,EAAE;QACR,KAAK,EAAE,MAAM,EAAE,CAAC;QAChB,IAAI,EAAE,MAAM,CAAC;KACd,EAAE,CAAC;IAEJ;;;;OAIG;IACH,WAAW,CAAC,EAAE,CACZ,KAAK,EAAE,MAAM,EACb,WAAW,EAAE,MAAM,GAAG,SAAS,EAC/B,OAAO,EAAE,eAAe,KACrB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAE7B;;;;;;OAMG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAE7B;;;;;;;OAOG;IACH,mBAAmB,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IAEvC,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb;;;;;OAKG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,iBAAiB;IAChC,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,MAAM,kBAAkB,GAC1B;IACE,IAAI,EAAE,WAAW,CAAC;IAClB,IAAI,EAAE,aAAa,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;CACjB,GACD;IACE,IAAI,EAAE,SAAS,CAAC;IAChB,IAAI,EAAE,WAAW,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAEN,wBAAgB,WAAW,CACzB,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,iBAAiB,EAC5B,OAAO,GAAE,eAAoB,GAC5B,MAAM,CAqBR;AAED,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,iBAAiB,EAC5B,OAAO,GAAE,eAAoB,GAC5B,kBAAkB,EAAE,CAiEtB;AAED,wBAAgB,YAAY,CAC1B,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,iBAAiB,EAC5B,OAAO,GAAE,eAAoB,GAC5B,iBAAiB,EAAE,CAwCrB;AAED,wBAAgB,gBAAgB,CAC9B,WAAW,EAAE,OAAO,EACpB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,IAAI,CAAC,eAAe,EAAE,qBAAqB,GAAG,SAAS,CAAC,GAChE,MAAM,CA+BR;AAOD,MAAM,MAAM,eAAe,GACvB;IACE,IAAI,EAAE,KAAK,CAAC;IACZ,GAAG,EAAE,SAAS,GAAG,SAAS,CAAC;CAC5B,GACD;IACE,IAAI,EAAE,WAAW,CAAC;CACnB,GACD;IACE,IAAI,EAAE,MAAM,CAAC;CACd,CAAC"}

package/dist/generate.js

@@ -1,10 +1,11 @@
 import { getAPIPageItems } from './build-routes.js';
-import { generateDocument, } from './utils/generate-document.js';
 import { idToTitle } from './utils/id-to-title.js';
-export async function generateAll(schemaId, processed, options = {}) {
+import { dump } from 'js-yaml';
+import Slugger from 'github-slugger';
+export function generateAll(schemaId, processed, options = {}) {
     const { document } = processed;
     const items = getAPIPageItems(document);
-    return generateDocument(schemaId, processed, {
+    return generatePage(schemaId, processed, {
         operations: items.operations,
         webhooks: items.webhooks,
         hasHead: true,
@@ -16,7 +17,7 @@ export async function generateAll(schemaId, processed, options = {}) {
         type: 'file',
     });
 }
-export async function generatePages(schemaId, processed, options = {}) {
+export function generatePages(schemaId, processed, options = {}) {
     const { document } = processed;
     const items = getAPIPageItems(document);
     const result = [];
@@ -30,7 +31,7 @@ export async function generatePages(schemaId, processed, options = {}) {
         result.push({
             type: 'operation',
             item,
-            content: generateDocument(schemaId, processed, {
+            content: generatePage(schemaId, processed, {
                 operations: [item],
                 hasHead: false,
             }, {
@@ -54,7 +55,7 @@ export async function generatePages(schemaId, processed, options = {}) {
         result.push({
             type: 'webhook',
             item,
-            content: generateDocument(schemaId, processed, {
+            content: generatePage(schemaId, processed, {
                 webhooks: [item],
                 hasHead: false,
             }, {
@@ -68,7 +69,7 @@ export async function generatePages(schemaId, processed, options = {}) {
     }
     return result;
 }
-export async function generateTags(schemaId, processed, options = {}) {
+export function generateTags(schemaId, processed, options = {}) {
     const { document } = processed;
     if (!document.tags)
         return [];
@@ -81,7 +82,7 @@ export async function generateTags(schemaId, processed, options = {}) {
             : idToTitle(tag.name);
         return {
             tag: tag.name,
-            content: generateDocument(schemaId, processed, {
+            content: generatePage(schemaId, processed, {
                 operations,
                 webhooks,
                 hasHead: true,
@@ -96,3 +97,99 @@ export async function generateTags(schemaId, processed, options = {}) {
         };
     });
 }
+export function generateDocument(frontmatter, content, options) {
+    const { addGeneratedComment = true, imports } = options;
+    const out = [];
+    const banner = dump(frontmatter).trim();
+    if (banner.length > 0)
+        out.push(`---\n${banner}\n---`);
+    if (addGeneratedComment) {
+        let commentContent = 'This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again.';
+        if (typeof addGeneratedComment === 'string') {
+            commentContent = addGeneratedComment;
+        }
+        commentContent = commentContent.replaceAll('/', '\\/');
+        out.push(`{/* ${commentContent} */}`);
+    }
+    if (imports) {
+        out.push(...imports
+            .map((item) => `import { ${item.names.join(', ')} } from ${JSON.stringify(item.from)};`)
+            .join('\n'));
+    }
+    out.push(content);
+    return out.join('\n\n');
+}
+function generatePage(schemaId, processed, pageProps, options, context) {
+    const { frontmatter, includeDescription = false } = options;
+    const extend = frontmatter?.(options.title, options.description, context);
+    const page = {
+        ...pageProps,
+        document: schemaId,
+    };
+    let meta;
+    if (page.operations?.length === 1) {
+        const operation = page.operations[0];
+        meta = {
+            method: operation.method.toUpperCase(),
+            route: operation.path,
+        };
+    }
+    const data = generateStaticData(processed.document, page);
+    const content = [];
+    if (options.description && includeDescription)
+        content.push(options.description);
+    content.push(pageContent(page));
+    return generateDocument({
+        title: options.title,
+        description: !includeDescription ? options.description : undefined,
+        full: true,
+        ...extend,
+        _openapi: {
+            ...meta,
+            ...data,
+            ...extend?._openapi,
+        },
+    }, content.join('\n\n'), options);
+}
+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 { toc, structuredData };
+}
+function pageContent(props) {
+    // filter extra properties in props
+    const operations = (props.operations ?? []).map((item) => ({
+        path: item.path,
+        method: item.method,
+    }));
+    const webhooks = (props.webhooks ?? []).map((item) => ({
+        name: item.name,
+        method: item.method,
+    }));
+    return `<APIPage document={${JSON.stringify(props.document)}} operations={${JSON.stringify(operations)}} webhooks={${JSON.stringify(webhooks)}} hasHead={${JSON.stringify(props.hasHead)}} />`;
+}

package/dist/render/api-page.js

@@ -3,12 +3,12 @@ import Slugger from 'github-slugger';
 import { Operation } from '../render/operation/index.js';
 import { createMethod } from '../server/create-method.js';
 import { createRenders } from '../render/renderer.js';
-import { processDocument, } from '../utils/process-document.js';
+import { processDocumentCached, } from '../utils/process-document.js';
 import { defaultAdapters } from '../media/adapter.js';
 export async function APIPage(props) {
     const { operations, hasHead = true, webhooks } = props;
     const processed = typeof props.document === 'string'
-        ? await processDocument(props.document)
+        ? await processDocumentCached(props.document)
         : await props.document;
     const ctx = await getContext(processed, props);
     const { document } = processed;

package/dist/render/schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/render/schema.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAY,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AACjD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AACrD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAe7C,wBAAgB,MAAM,CAAC,EACrB,IAAI,EACJ,MAAM,EACN,QAAgB,EAChB,QAAgB,EAChB,SAAiB,EACjB,EAAe,EACf,GAAG,EAAE,aAAa,GACnB,EAAE;IACD,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,MAAM,EAAE,cAAc,CAAC;IACvB,EAAE,CAAC,EAAE,UAAU,GAAG,MAAM,CAAC;IAEzB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,GAAG,EAAE,aAAa,CAAC;CACpB,GAAG,SAAS,CAoTZ"}
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/render/schema.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAY,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AACjD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AACrD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAe7C,wBAAgB,MAAM,CAAC,EACrB,IAAI,EACJ,MAAM,EACN,QAAgB,EAChB,QAAgB,EAChB,SAAiB,EACjB,EAAe,EACf,GAAG,EAAE,aAAa,GACnB,EAAE;IACD,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,MAAM,EAAE,cAAc,CAAC;IACvB,EAAE,CAAC,EAAE,UAAU,GAAG,MAAM,CAAC;IAEzB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,GAAG,EAAE,aAAa,CAAC;CACpB,GAAG,SAAS,CA+TZ"}

package/dist/render/schema.js

@@ -7,6 +7,12 @@ import { Tabs, TabsContent, TabsList, TabsTrigger, } from 'fumadocs-ui/component
 export function Schema({ name, schema, required = false, readOnly = false, writeOnly = false, as = 'property', ctx: renderContext, }) {
     const { renderer } = renderContext;
     function propertyBody(schema, renderPrimitive, ctx) {
+        if (ctx.stack.has(schema))
+            return;
+        const next = {
+            ...ctx,
+            stack: ctx.stack.next(schema),
+        };
         if (Array.isArray(schema.type)) {
             const items = schema.type.flatMap((type) => {
                 const composed = {
@@ -20,24 +26,25 @@ export function Schema({ name, schema, required = false, readOnly = false, write
             if (items.length === 0)
                 return;
             if (items.length === 1)
-                return propertyBody(items[0], renderPrimitive, ctx);
+                return propertyBody(items[0], renderPrimitive, next);
             return (_jsxs(Tabs, { defaultValue: items[0].type, children: [_jsx(TabsList, { children: items.map((item) => (_jsx(TabsTrigger, { value: item.type, children: schemaToString(item, renderContext.schema) }, item.type))) }), items.map((item) => (_jsxs(TabsContent, { value: item.type, children: [item.description && _jsx(Markdown, { text: item.description }), propertyInfo(item), renderPrimitive(item, ctx)] }, item.type)))] }));
         }
         if (schema.oneOf) {
             const oneOf = schema.oneOf.filter((item) => isComplexType(item));
-            if (oneOf.length === 0)
+            if (oneOf.length === 0 || oneOf.some((item) => ctx.stack.has(item)))
                 return;
             if (oneOf.length === 1) {
-                return propertyBody(oneOf[0], renderPrimitive, ctx);
+                return propertyBody(oneOf[0], renderPrimitive, next);
             }
-            return (_jsxs(Tabs, { defaultValue: "0", children: [_jsx(TabsList, { children: oneOf.map((item, i) => (_jsx(TabsTrigger, { value: i.toString(), children: schemaToString(item, renderContext.schema) }, i))) }), oneOf.map((item, i) => (_jsxs(TabsContent, { value: i.toString(), children: [item.description && _jsx(Markdown, { text: item.description }), propertyInfo(item), propertyBody(item, (child, ctx) => primitiveBody(child, ctx, false, true), ctx)] }, i)))] }));
+            return (_jsxs(Tabs, { defaultValue: "0", children: [_jsx(TabsList, { children: oneOf.map((item, i) => (_jsx(TabsTrigger, { value: i.toString(), children: schemaToString(item, renderContext.schema) }, i))) }), oneOf.map((item, i) => (_jsxs(TabsContent, { value: i.toString(), children: [item.description && _jsx(Markdown, { text: item.description }), propertyInfo(item), propertyBody(item, (child, ctx) => primitiveBody(child, ctx, false, true), next)] }, i)))] }));
         }
         const of = schema.allOf ?? schema.anyOf;
         if (of) {
-            const arr = of.filter((item) => !ctx.stack.has(item));
-            if (arr.length === 0)
+            if (of.length === 0)
+                return;
+            if (of.some((item) => typeof item === 'object' && ctx.stack.has(item)))
                 return;
-            const combined = combineSchema(arr);
+            const combined = combineSchema(of);
             if (typeof combined === 'boolean')
                 return;
             return renderPrimitive(combined, ctx);
@@ -99,9 +106,9 @@ export function Schema({ name, schema, required = false, readOnly = false, write
         return (_jsx("div", { className: "flex flex-wrap gap-2 not-prose", children: fields.map((field) => (_jsxs("div", { className: "bg-fd-secondary border rounded-lg text-xs p-1.5 shadow-md", children: [_jsx("span", { className: "font-medium me-2", children: field.key }), _jsx("code", { className: "text-fd-muted-foreground", children: field.value })] }, field.key))) }));
     }
     function primitiveBody(schema, ctx, collapsible, nested) {
+        if (ctx.stack.has(schema))
+            return _jsx("p", { children: "Recursive" });
         if (schema.type === 'object') {
-            if (ctx.stack.has(schema))
-                return _jsx("p", { children: "Recursive" });
             const props = Object.entries(schema.properties ?? {});
             const patternProps = Object.entries(schema.patternProperties ?? {});
             const next = {
@@ -138,12 +145,14 @@ export function Schema({ name, schema, required = false, readOnly = false, write
         else if (schema === false) {
             return _jsx(renderer.Property, { name: key, type: "never", ...props });
         }
+        if (ctx.stack.has(schema))
+            return;
         if ((schema.readOnly && !readOnly) || (schema.writeOnly && !writeOnly))
             return;
         return (_jsxs(renderer.Property, { name: key, type: schemaToString(schema, renderContext.schema), deprecated: schema.deprecated, ...props, children: [schema.description && _jsx(Markdown, { text: schema.description }), propertyInfo(schema), propertyBody(schema, (child, ctx) => primitiveBody(child, ctx, true, true), ctx)] }));
     }
     const context = {
-        stack: schemaStack(),
+        stack: schemaStack(renderContext),
     };
     if (typeof schema === 'boolean' ||
         as === 'property' ||
@@ -151,12 +160,17 @@ export function Schema({ name, schema, required = false, readOnly = false, write
         return property(name, schema, context, { required });
     return propertyBody(schema, (child, ctx) => primitiveBody(child, ctx, false, false), context);
 }
-function schemaStack(parent) {
-    const titles = new Set();
-    const history = new WeakSet();
+function schemaStack(renderContext, parent) {
+    const ids = new Set();
+    function getId(schema) {
+        if (typeof schema !== 'object')
+            return;
+        return schema.title ?? renderContext.schema.dereferenceMap.get(schema);
+    }
     return {
+        history: parent ? [...parent.history] : [],
         next(...schemas) {
-            const child = schemaStack(this);
+            const child = schemaStack(renderContext, this);
             for (const item of schemas) {
                 child.add(item);
             }
@@ -165,18 +179,23 @@ function schemaStack(parent) {
         add(schema) {
             if (typeof schema !== 'object')
                 return;
-            if (schema.title)
-                titles.add(schema.title);
-            history.add(schema);
+            const id = getId(schema);
+            if (id)
+                ids.add(id);
+            this.history.push(schema);
         },
         has(schema) {
-            if (typeof schema !== 'object')
-                return false;
-            if (parent && parent.has(schema))
+            if (this.history.length > 30) {
+                console.warn(`[Fumadocs OpenAPI] schema depth exceeded 30, this might be unexpected.`);
+                // stopping at here
                 return true;
-            if (schema.title && titles.has(schema.title))
+            }
+            if (parent && parent.has(schema))
                 return true;
-            return history.has(schema);
+            const id = getId(schema);
+            if (id)
+                return ids.has(id);
+            return this.history.includes(schema);
         },
     };
 }

package/dist/server/create.d.ts

@@ -56,9 +56,6 @@ export interface OpenAPIOptions extends SharedOpenAPIOptions {
      * - a function returning records of downloaded schemas.
      */
     input?: string[] | (() => Promise<SchemaMap>);
-    /**
-     * By default, it is disabled on dev mode
-     */
     disableCache?: boolean;
 }
 export interface OpenAPIServer {

package/dist/server/create.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"create.d.ts","sourceRoot":"","sources":["../../src/server/create.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC7C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAClD,OAAO,KAAK,EACV,YAAY,EACZ,iBAAiB,EACjB,uBAAuB,EACxB,MAAM,OAAO,CAAC;AACf,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AACjD,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5D,OAAO,EAEL,KAAK,iBAAiB,EACvB,MAAM,0BAA0B,CAAC;AAElC,KAAK,SAAS,CAAC,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;AACnC;;GAEG;AACH,KAAK,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,QAAQ,GAAG,SAAS,CAAC,QAAQ,CAAC,CAAC;AAC3E,KAAK,kBAAkB,GAAG,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;AAE5D,MAAM,WAAW,oBAAoB;IACnC;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB,QAAQ,CAAC,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC;IAE7B;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAE5B;;;;;;;OAOG;IACH,wBAAwB,CAAC,EACrB,CAAC,CACC,MAAM,EAAE,WAAW,CAAC,iBAAiB,CAAC,EACtC,UAAU,EAAE,MAAM,KACf,SAAS,CAAC,MAAM,CAAC,CAAC,GACvB,KAAK,CAAC;IAEV;;OAEG;IACH,mBAAmB,CAAC,EAAE,CAAC,MAAM,EAAE,iBAAiB,KAAK,SAAS,CAAC,UAAU,EAAE,CAAC,CAAC;IAE7E,YAAY,CAAC,EAAE,IAAI,CAAC,uBAAuB,EAAE,MAAM,CAAC,GAClD,iBAAiB,CAAC,YAAY,CAAC,CAAC;IAElC;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAE7B,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;CAC9C;AAED,MAAM,WAAW,cAAe,SAAQ,oBAAoB;IAC1D;;;;;OAKG;IACH,KAAK,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC;IAE9C;;OAEG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,aAAa;IAC5B,eAAe,EAAE,CAAC,IAAI,EAAE,YAAY,KAAK,YAAY,CAAC;IACtD,WAAW,EAAE,OAAO,WAAW,CAAC;IAChC,UAAU,EAAE,MAAM,OAAO,CAAC,kBAAkB,CAAC,CAAC;CAC/C;AAED,wBAAgB,aAAa,CAAC,OAAO,GAAE,cAAmB,GAAG,aAAa,CA8CzE;AAED,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,OAAO,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,UAAU,CAEtE"}
+{"version":3,"file":"create.d.ts","sourceRoot":"","sources":["../../src/server/create.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC7C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAClD,OAAO,KAAK,EACV,YAAY,EACZ,iBAAiB,EACjB,uBAAuB,EACxB,MAAM,OAAO,CAAC;AACf,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AACjD,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5D,OAAO,EAGL,KAAK,iBAAiB,EACvB,MAAM,0BAA0B,CAAC;AAElC,KAAK,SAAS,CAAC,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;AACnC;;GAEG;AACH,KAAK,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,QAAQ,GAAG,SAAS,CAAC,QAAQ,CAAC,CAAC;AAC3E,KAAK,kBAAkB,GAAG,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;AAE5D,MAAM,WAAW,oBAAoB;IACnC;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB,QAAQ,CAAC,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC;IAE7B;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAE5B;;;;;;;OAOG;IACH,wBAAwB,CAAC,EACrB,CAAC,CACC,MAAM,EAAE,WAAW,CAAC,iBAAiB,CAAC,EACtC,UAAU,EAAE,MAAM,KACf,SAAS,CAAC,MAAM,CAAC,CAAC,GACvB,KAAK,CAAC;IAEV;;OAEG;IACH,mBAAmB,CAAC,EAAE,CAAC,MAAM,EAAE,iBAAiB,KAAK,SAAS,CAAC,UAAU,EAAE,CAAC,CAAC;IAE7E,YAAY,CAAC,EAAE,IAAI,CAAC,uBAAuB,EAAE,MAAM,CAAC,GAClD,iBAAiB,CAAC,YAAY,CAAC,CAAC;IAElC;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAE7B,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;CAC9C;AAED,MAAM,WAAW,cAAe,SAAQ,oBAAoB;IAC1D;;;;;OAKG;IACH,KAAK,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC;IAE9C,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,aAAa;IAC5B,eAAe,EAAE,CAAC,IAAI,EAAE,YAAY,KAAK,YAAY,CAAC;IACtD,WAAW,EAAE,OAAO,WAAW,CAAC;IAChC,UAAU,EAAE,MAAM,OAAO,CAAC,kBAAkB,CAAC,CAAC;CAC/C;AAED,wBAAgB,aAAa,CAAC,OAAO,GAAE,cAAmB,GAAG,aAAa,CA4CzE;AAED,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,OAAO,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,UAAU,CAEtE"}

package/dist/server/create.js

@@ -1,18 +1,18 @@
 import { createProxy } from '../server/proxy.js';
-import { processDocument, } from '../utils/process-document.js';
+import { processDocument, processDocumentCached, } from '../utils/process-document.js';
 export function createOpenAPI(options = {}) {
-    const { input = [], disableCache = process.env.NODE_ENV === 'development', ...shared } = options;
+    const { input = [], disableCache = false, ...shared } = options;
     let schemas;
     async function getSchemas() {
         const out = {};
         if (Array.isArray(input)) {
             await Promise.all(input.map(async (item) => {
-                out[item] = await processDocument(item, disableCache);
+                out[item] = await processDocument(item);
             }));
         }
         else {
             await Promise.all(Object.entries(await input()).map(async ([k, v]) => {
-                out[k] = await processDocument(v, disableCache);
+                out[k] = await processDocument(v);
             }));
         }
         return out;
@@ -20,6 +20,8 @@ export function createOpenAPI(options = {}) {
     return {
         createProxy,
         async getSchemas() {
+            if (disableCache)
+                return getSchemas();
             return (schemas ?? (schemas = getSchemas()));
         },
         getAPIPageProps({ document, ...props }) {
@@ -28,7 +30,7 @@ export function createOpenAPI(options = {}) {
                 ...props,
                 document: typeof document === 'string'
                     ? this.getSchemas().then((map) => {
-                        return map[document] ?? processDocument(document, disableCache);
+                        return map[document] ?? processDocumentCached(document);
                     })
                     : document,
             };

package/dist/utils/process-document.d.ts

@@ -6,8 +6,9 @@ export type ProcessedDocument = {
     dereferenceMap: DereferenceMap;
     downloaded: Document;
 };
+export declare function processDocumentCached(input: string | OpenAPIV3_1.Document | OpenAPIV3.Document): Promise<ProcessedDocument>;
 /**
  * process & reference input document to a Fumadocs OpenAPI compatible format
  */
-export declare function processDocument(input: string | OpenAPIV3_1.Document | OpenAPIV3.Document, disableCache?: boolean): Promise<ProcessedDocument>;
+export declare function processDocument(input: string | OpenAPIV3_1.Document | OpenAPIV3.Document): Promise<ProcessedDocument>;
 //# sourceMappingURL=process-document.d.ts.map

package/dist/utils/process-document.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"process-document.d.ts","sourceRoot":"","sources":["../../src/utils/process-document.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACxD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAClD,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAI5D,MAAM,MAAM,iBAAiB,GAAG;IAC9B,QAAQ,EAAE,WAAW,CAAC,QAAQ,CAAC,CAAC;IAChC,cAAc,EAAE,cAAc,CAAC;IAC/B,UAAU,EAAE,QAAQ,CAAC;CACtB,CAAC;AAIF;;GAEG;AACH,wBAAsB,eAAe,CACnC,KAAK,EAAE,MAAM,GAAG,WAAW,CAAC,QAAQ,GAAG,SAAS,CAAC,QAAQ,EACzD,YAAY,UAAQ,GACnB,OAAO,CAAC,iBAAiB,CAAC,CA+B5B"}
+{"version":3,"file":"process-document.d.ts","sourceRoot":"","sources":["../../src/utils/process-document.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACxD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAClD,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAI5D,MAAM,MAAM,iBAAiB,GAAG;IAC9B,QAAQ,EAAE,WAAW,CAAC,QAAQ,CAAC,CAAC;IAChC,cAAc,EAAE,cAAc,CAAC;IAC/B,UAAU,EAAE,QAAQ,CAAC;CACtB,CAAC;AAIF,wBAAsB,qBAAqB,CACzC,KAAK,EAAE,MAAM,GAAG,WAAW,CAAC,QAAQ,GAAG,SAAS,CAAC,QAAQ,GACxD,OAAO,CAAC,iBAAiB,CAAC,CAS5B;AAED;;GAEG;AACH,wBAAsB,eAAe,CACnC,KAAK,EAAE,MAAM,GAAG,WAAW,CAAC,QAAQ,GAAG,SAAS,CAAC,QAAQ,GACxD,OAAO,CAAC,iBAAiB,CAAC,CAoB5B"}

package/dist/utils/process-document.js

@@ -1,13 +1,20 @@
 import { bundle, dereference, upgrade } from '@scalar/openapi-parser';
 import { fetchUrls, readFiles } from '@scalar/openapi-parser/plugins';
 const cache = new Map();
+export async function processDocumentCached(input) {
+    if (typeof input !== 'string')
+        return processDocument(input);
+    const cached = cache.get(input);
+    if (cached)
+        return cached;
+    const processed = await processDocument(input);
+    cache.set(input, processed);
+    return processed;
+}
 /**
  * process & reference input document to a Fumadocs OpenAPI compatible format
  */
-export async function processDocument(input, disableCache = false) {
-    const cached = !disableCache && typeof input === 'string' ? cache.get(input) : null;
-    if (cached)
-        return cached;
+export async function processDocument(input) {
     const dereferenceMap = new Map();
     let document = await bundle(input, {
         plugins: [fetchUrls(), readFiles()],
@@ -20,13 +27,9 @@ export async function processDocument(input, disableCache = false) {
             dereferenceMap.set(schema, ref);
         },
     });
-    const processed = {
+    return {
         document: dereferenced,
         dereferenceMap,
         downloaded: document,
     };
-    if (!disableCache && typeof input === 'string') {
-        cache.set(input, processed);
-    }
-    return processed;
 }

package/dist/utils/url.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"url.d.ts","sourceRoot":"","sources":["../../src/utils/url.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEtD,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAM9D;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAM1D;AAED,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAChC,MAAM,CAMR;AAED,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,EAChB,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,WAAW,GAC3B,MAAM,CAyBR"}
+{"version":3,"file":"url.d.ts","sourceRoot":"","sources":["../../src/utils/url.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEtD,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAM9D;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAM1D;AAED,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAChC,MAAM,CAMR;AAED,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,EAChB,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,WAAW,GAC3B,MAAM,CAoCR"}

package/dist/utils/url.js

@@ -25,6 +25,7 @@ export function resolveServerUrl(template, variables) {
     return template;
 }
 export function resolveRequestData(pathname, { path, query }) {
+    // First, resolve path parameters in the pathname
     for (const key in path) {
         const param = path[key];
         if (Array.isArray(param.value)) {
@@ -34,17 +35,25 @@ export function resolveRequestData(pathname, { path, query }) {
             pathname = pathname.replace(`{${key}}`, param.value);
         }
     }
-    const searchParams = new URLSearchParams();
+    // Check if pathname already contains query parameters (legacy API support)
+    const [pathPart, existingQueryString] = pathname.split('?', 2);
+    // Parse existing query parameters from the pathname if they exist
+    const searchParams = new URLSearchParams(existingQueryString || '');
+    // Add new query parameters from the RequestData
     for (const key in query) {
         const param = query[key];
         if (Array.isArray(param.value)) {
+            // Remove existing parameter first to avoid duplicates
+            searchParams.delete(key);
             for (const item of param.value) {
                 searchParams.append(key, item);
             }
         }
         else {
-            searchParams.append(key, param.value);
+            // Set (replace if exists) the parameter value
+            searchParams.set(key, param.value);
         }
     }
-    return searchParams.size > 0 ? `${pathname}?${searchParams}` : pathname;
+    // Return the reconstructed URL
+    return searchParams.size > 0 ? `${pathPart}?${searchParams}` : pathPart;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fumadocs-openapi",
-  "version": "9.2.3",
+  "version": "9.3.1",
   "description": "Generate MDX docs for your OpenAPI spec",
   "keywords": [
     "NextJs",
@@ -54,6 +54,7 @@
     "ajv": "^8.17.1",
     "class-variance-authority": "^0.7.1",
     "github-slugger": "^2.0.0",
+    "gray-matter": "^4.0.3",
     "hast-util-to-jsx-runtime": "^2.3.6",
     "js-yaml": "^4.1.0",
     "next-themes": "^0.4.6",
@@ -64,8 +65,8 @@
     "shiki": "^3.11.0",
     "tinyglobby": "^0.2.14",
     "xml-js": "^1.6.11",
-    "fumadocs-core": "15.7.2",
-    "fumadocs-ui": "15.7.2"
+    "fumadocs-core": "15.7.4",
+    "fumadocs-ui": "15.7.4"
   },
   "devDependencies": {
     "@scalar/api-client-react": "^1.3.29",

package/dist/utils/generate-document.d.ts

@@ -1,17 +0,0 @@
-import type { ApiPageProps } from '../render/api-page.js';
-import type { GenerateOptions } from '../generate.js';
-import type { TagObject } from '../types.js';
-import type { ProcessedDocument } from '../utils/process-document.js';
-export type DocumentContext = {
-    type: 'tag';
-    tag: TagObject | undefined;
-} | {
-    type: 'operation';
-} | {
-    type: 'file';
-};
-export declare function generateDocument(schemaId: string, processed: ProcessedDocument, pageProps: Omit<ApiPageProps, 'document'>, options: GenerateOptions & {
-    title: string;
-    description?: string;
-}, context: DocumentContext): string;
-//# sourceMappingURL=generate-document.d.ts.map

package/dist/utils/generate-document.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"generate-document.d.ts","sourceRoot":"","sources":["../../src/utils/generate-document.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,YAAY,EAGb,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD,OAAO,KAAK,EAAY,SAAS,EAAE,MAAM,SAAS,CAAC;AAEnD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAOlE,MAAM,MAAM,eAAe,GACvB;IACE,IAAI,EAAE,KAAK,CAAC;IACZ,GAAG,EAAE,SAAS,GAAG,SAAS,CAAC;CAC5B,GACD;IACE,IAAI,EAAE,WAAW,CAAC;CACnB,GACD;IACE,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEN,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,iBAAiB,EAC5B,SAAS,EAAE,IAAI,CAAC,YAAY,EAAE,UAAU,CAAC,EACzC,OAAO,EAAE,eAAe,GAAG;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,EACD,OAAO,EAAE,eAAe,GACvB,MAAM,CAkER"}

package/dist/utils/generate-document.js

@@ -1,94 +0,0 @@
-import { dump } from 'js-yaml';
-import Slugger from 'github-slugger';
-import { idToTitle } from '../utils/id-to-title.js';
-export function generateDocument(schemaId, processed, pageProps, options, context) {
-    const { frontmatter, includeDescription = false, addGeneratedComment = true, } = options;
-    const out = [];
-    const extend = frontmatter?.(options.title, options.description, context);
-    const page = {
-        ...pageProps,
-        document: schemaId,
-    };
-    let meta;
-    if (page.operations?.length === 1) {
-        const operation = page.operations[0];
-        meta = {
-            method: operation.method.toUpperCase(),
-            route: operation.path,
-        };
-    }
-    const data = generateStaticData(processed.document, page);
-    const banner = dump({
-        title: options.title,
-        description: !includeDescription ? options.description : undefined,
-        full: true,
-        ...extend,
-        _openapi: {
-            ...meta,
-            ...data,
-            ...extend?._openapi,
-        },
-    }).trim();
-    if (banner.length > 0)
-        out.push(`---\n${banner}\n---`);
-    if (addGeneratedComment !== false) {
-        let commentContent = 'This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again.';
-        if (typeof addGeneratedComment === 'string') {
-            commentContent = addGeneratedComment;
-        }
-        commentContent = commentContent.replaceAll('/', '\\/');
-        out.push(`{/* ${commentContent} */}`);
-    }
-    const imports = options.imports
-        ?.map((item) => `import { ${item.names.join(', ')} } from ${JSON.stringify(item.from)};`)
-        .join('\n');
-    if (imports) {
-        out.push(imports);
-    }
-    if (options.description && includeDescription)
-        out.push(options.description);
-    out.push(pageContent(page));
-    return out.join('\n\n');
-}
-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 { toc, structuredData };
-}
-function pageContent(props) {
-    // filter extra properties in props
-    const operations = (props.operations ?? []).map((item) => ({
-        path: item.path,
-        method: item.method,
-    }));
-    const webhooks = (props.webhooks ?? []).map((item) => ({
-        name: item.name,
-        method: item.method,
-    }));
-    return `<APIPage document={${JSON.stringify(props.document)}} operations={${JSON.stringify(operations)}} webhooks={${JSON.stringify(webhooks)}} hasHead={${JSON.stringify(props.hasHead)}} />`;
-}