fumadocs-openapi 9.3.0 → 9.3.2

package/dist/generate-file.d.ts

@@ -68,9 +68,16 @@ interface IndexItem {
     title?: string;
     description?: string;
     /**
-     * Only include items from specific input schema ids
+     * Specify linked pages:
+     * - items in `inputs` to include all generated pages of a specific schema.
+     * - specific Markdown/MDX files.
      */
-    only?: string[];
+    only?: (string | OutputFile)[];
+}
+interface HookContext {
+    files: OutputFile[];
+    readonly generated: Record<string, OutputFile[]>;
+    readonly documents: Record<string, ProcessedDocument>;
 }
 interface BaseConfig extends GenerateOptions {
     /**
@@ -91,7 +98,7 @@ interface BaseConfig extends GenerateOptions {
      * Generate index files with cards linking to generated pages.
      */
     index?: {
-        items: IndexItem[];
+        items: IndexItem[] | ((ctx: HookContext) => IndexItem[]);
         /**
          * Generate URLs for cards
          */
@@ -106,7 +113,7 @@ interface BaseConfig extends GenerateOptions {
     /**
      * Can add/change/remove output files before writing to file system
      **/
-    beforeWrite?: (files: OutputFile[]) => void | Promise<void>;
+    beforeWrite?: (this: HookContext, files: OutputFile[]) => void | Promise<void>;
 }
 export declare function generateFiles(options: Config): Promise<void>;
 export declare function generateFilesOnly(options: Config): Promise<OutputFile[]>;

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,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;IACrB;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB;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,CAAC;QAEnB;;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,CAAC,KAAK,EAAE,UAAU,EAAE,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7D;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,CA8CvB"}
+{"version":3,"file":"generate-file.d.ts","sourceRoot":"","sources":["../src/generate-file.ts"],"names":[],"mappings":"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"}

package/dist/generate-file.js

@@ -17,40 +17,52 @@ 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]);
+        }
+        else {
+            throw new Error(`input not found: ${item}`);
         }
-        if (patterns.length > 0)
-            targets.push(...(await glob(patterns, { cwd })));
-        await Promise.all(targets.map(async (item) => {
-            schemas[item] = await processDocumentCached(path.join(cwd, 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.');
     }
-    const documentFiles = new Map();
-    const files = [];
-    for (const [id, schema] of resolvedSchemas) {
+    for (const [id, schema] of entries) {
         const result = generateFromDocument(id, schema, options);
         files.push(...result);
-        documentFiles.set(id, result);
+        generated[id] = result;
     }
+    const context = {
+        files,
+        generated,
+        documents: schemas,
+    };
     if (options.index) {
-        files.push(...generateIndexFiles(documentFiles, options));
+        writeIndexFiles(context, options);
     }
-    beforeWrite?.(files);
-    return files;
+    await beforeWrite?.call(context, context.files);
+    return context.files;
 }
 function generateFromDocument(schemaId, processed, options) {
     const files = [];
@@ -171,11 +183,10 @@ function getOutputPathFromRoute(path) {
     })
         .join('/') ?? '');
 }
-function generateIndexFiles(generatedFiles, options) {
-    const files = [];
+function writeIndexFiles(context, options) {
     const { index, output, cwd = process.cwd() } = options;
     if (!index)
-        return files;
+        return;
     const { items, url } = index;
     let urlFn;
     if (typeof url === 'object') {
@@ -186,25 +197,25 @@ function generateIndexFiles(generatedFiles, options) {
     else {
         urlFn = url;
     }
-    function fileContent(item) {
+    function fileContent(index) {
+        const generatedPages = context.generated;
         const content = [];
         content.push('<Cards>');
-        const files = [];
-        if (item.only) {
-            for (let id of item.only) {
-                if (id.startsWith('./'))
-                    id = id.slice(2);
-                const result = generatedFiles.get(id);
-                if (!result)
-                    throw new Error(`${id} does not exist on "input", available: ${Array.from(generatedFiles.keys())}.`);
-                files.push(...result);
+        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);
             }
         }
-        else {
-            for (const value of generatedFiles.values())
-                files.push(...value);
-        }
-        for (const file of files) {
+        for (const file of files.values()) {
             const isContent = file.path.endsWith('.mdx') || file.path.endsWith('.md');
             if (!isContent)
                 continue;
@@ -215,18 +226,18 @@ function generateIndexFiles(generatedFiles, options) {
         }
         content.push('</Cards>');
         return generateDocument({
-            title: item.title ?? 'Overview',
-            description: item.description,
+            title: index.title ?? 'Overview',
+            description: index.description,
         }, content.join('\n'), options);
     }
     const outputDir = path.join(cwd, output);
-    for (const item of items) {
-        files.push({
-            path: path.join(outputDir, path.extname(item.path).length === 0 ? `${item.path}.mdx` : item.path),
+    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),
         });
     }
-    return files;
 }
 function defaultSlugify(s) {
     return s.replace(/\s+/g, '-').toLowerCase();

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.3.0",
+  "version": "9.3.2",
   "description": "Generate MDX docs for your OpenAPI spec",
   "keywords": [
     "NextJs",
@@ -62,18 +62,18 @@
     "react-hook-form": "^7.62.0",
     "remark": "^15.0.1",
     "remark-rehype": "^11.1.2",
-    "shiki": "^3.11.0",
+    "shiki": "^3.12.0",
     "tinyglobby": "^0.2.14",
     "xml-js": "^1.6.11",
-    "fumadocs-core": "15.7.3",
-    "fumadocs-ui": "15.7.3"
+    "fumadocs-core": "15.7.5",
+    "fumadocs-ui": "15.7.5"
   },
   "devDependencies": {
-    "@scalar/api-client-react": "^1.3.29",
+    "@scalar/api-client-react": "^1.3.31",
     "@types/js-yaml": "^4.0.9",
     "@types/node": "24.3.0",
     "@types/openapi-sampler": "^1.0.3",
-    "@types/react": "^19.1.11",
+    "@types/react": "^19.1.12",
     "json-schema-typed": "^8.0.1",
     "openapi-types": "^12.1.3",
     "tailwindcss": "^4.1.12",