fumadocs-openapi 5.7.4 → 5.8.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { OpenAPIV3 } from 'openapi-types';
+import { OpenAPIV3_1, OpenAPIV3 } from 'openapi-types';
 import Slugger from 'github-slugger';
 import { ComponentType, ReactNode } from 'react';
 import { CodeToHastOptionsCommon, CodeOptionsThemes, BuiltinTheme } from 'shiki';
@@ -72,6 +72,7 @@ interface APIInfoProps {
     method: string;
     route: string;
     baseUrls: string[];
+    head: ReactNode;
     children: ReactNode;
 }
 interface PropertyProps {
@@ -127,6 +128,11 @@ interface Renderer {
     APIPlayground: ComponentType<APIPlaygroundProps>;
 }
 
+type NoReference<T> = T extends (infer I)[] ? NoReference<I>[] : T extends ReferenceObject ? Exclude<T, ReferenceObject> : T extends object ? {
+    [K in keyof T]: NoReference<T[K]>;
+} : T;
+type ParsedSchema = OpenAPIV3_1.SchemaObject;
+
 /**
  * Sample info of endpoint
  */
@@ -137,7 +143,7 @@ interface EndpointSample {
     url: string;
     method: string;
     body?: {
-        schema: OpenAPIV3.SchemaObject;
+        schema: ParsedSchema;
         mediaType: string;
         sample: unknown;
     };
@@ -147,12 +153,12 @@ interface EndpointSample {
 interface ResponseSample {
     mediaType: string;
     sample: unknown;
-    schema: OpenAPIV3.SchemaObject;
+    schema: ParsedSchema;
 }
 interface ParameterSample {
     name: string;
     in: string;
-    schema: OpenAPIV3.SchemaObject;
+    schema: ParsedSchema;
     sample: unknown;
 }
 
@@ -162,22 +168,38 @@ interface CodeSample {
     source: string | ((endpoint: EndpointSample) => string | undefined) | false;
 }
 
+type Document = OpenAPIV3_1.Document;
+type OperationObject = OpenAPIV3_1.OperationObject;
+type ParameterObject = OpenAPIV3_1.ParameterObject;
+type SecurityRequirementObject = OpenAPIV3_1.SecurityRequirementObject;
+type SecuritySchemeObject = OpenAPIV3_1.SecuritySchemeObject;
+type ReferenceObject = OpenAPIV3_1.ReferenceObject;
+type PathItemObject = OpenAPIV3_1.PathItemObject;
+type TagObject = OpenAPIV3_1.TagObject;
 interface RouteInformation {
     path: string;
     summary?: string;
     description?: string;
     methods: MethodInformation[];
 }
-interface MethodInformation extends OpenAPIV3.OperationObject {
-    parameters: OpenAPIV3.ParameterObject[];
+type MethodInformation = NoReference<OperationObject> & {
     method: string;
-}
+};
 type Awaitable<T> = T | Promise<T>;
+/**
+ * Dereferenced value and its original `$ref` value
+ */
+type DereferenceMap = Map<unknown, string>;
 interface RenderContext {
     renderer: Renderer;
-    document: OpenAPIV3.Document;
+    /**
+     * dereferenced schema
+     */
+    document: NoReference<Document>;
     baseUrl: string;
+    baseUrls: string[];
     slugger: Slugger;
+    dereferenceMap: DereferenceMap;
     /**
      * Generate TypeScript definitions from response schema.
      *
@@ -194,24 +216,26 @@ interface RenderContext {
     shikiOptions?: Omit<CodeToHastOptionsCommon, 'lang'> & CodeOptionsThemes<BuiltinTheme>;
 }
 
+type DocumentInput = string | OpenAPIV3_1.Document | OpenAPIV3.Document;
+
+interface WebhookItem {
+    name: string;
+    method: OpenAPIV3_1.HttpMethods;
+}
+interface OperationItem {
+    path: string;
+    method: OpenAPIV3_1.HttpMethods;
+}
+
 type DocumentContext = {
     type: 'tag';
-    tag: OpenAPIV3.TagObject | undefined;
-    routes: RouteInformation[];
+    tag: TagObject | undefined;
 } | {
     type: 'operation';
-    /**
-     * information of the route
-     */
-    route: RouteInformation;
-    /**
-     * information of the method (API Endpoint)
-     */
-    endpoint: MethodInformation;
 } | {
     type: 'file';
-    routes: RouteInformation[];
 };
+
 interface GenerateOptions {
     /**
      * Additional imports of your MDX components.
@@ -238,14 +262,22 @@ interface GenerateTagOutput {
     tag: string;
     content: string;
 }
-interface GenerateOperationOutput {
+type GeneratePageOutput = {
+    type: 'operation';
+    pathItem: NoReference<PathItemObject>;
+    operation: NoReference<OperationObject>;
+    item: OperationItem;
     content: string;
-    method: MethodInformation;
-    route: RouteInformation;
-}
-declare function generateAll(pathOrDocument: string | OpenAPIV3.Document, options?: GenerateOptions): Promise<string>;
-declare function generateOperations(pathOrDocument: string | OpenAPIV3.Document, options?: GenerateOptions): Promise<GenerateOperationOutput[]>;
-declare function generateTags(pathOrDocument: string | OpenAPIV3.Document, options?: GenerateOptions): Promise<GenerateTagOutput[]>;
+} | {
+    type: 'webhook';
+    pathItem: NoReference<PathItemObject>;
+    operation: NoReference<OperationObject>;
+    item: WebhookItem;
+    content: string;
+};
+declare function generateAll(pathOrDocument: DocumentInput, options?: GenerateOptions): Promise<string>;
+declare function generatePages(pathOrDocument: DocumentInput, options?: GenerateOptions): Promise<GeneratePageOutput[]>;
+declare function generateTags(pathOrDocument: DocumentInput, options?: GenerateOptions): Promise<GenerateTagOutput[]>;
 
 interface Config extends GenerateOptions {
     /**
@@ -284,4 +316,4 @@ interface Config extends GenerateOptions {
 }
 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 };
+export { type Config, type DereferenceMap, type Document, type GenerateOptions, type GeneratePageOutput, type GenerateTagOutput, type MethodInformation, type OperationObject, type ParameterObject, type PathItemObject, type ReferenceObject, type RenderContext, type RouteInformation, type SecurityRequirementObject, type SecuritySchemeObject, type TagObject, generateAll, generateFiles, generatePages, generateTags };

package/dist/index.js

@@ -1,29 +1,11 @@
 import { resolve, join, parse, dirname } from 'node:path';
-import Parser from '@apidevtools/json-schema-ref-parser';
 import { dump } from 'js-yaml';
 import Slugger from 'github-slugger';
+import Parser from '@apidevtools/json-schema-ref-parser';
+import { upgrade } from '@scalar/openapi-parser';
 import { mkdir, writeFile } from 'node:fs/promises';
 import fg from 'fast-glob';
 
-function noRef(v) {
-    return v;
-}
-
-/**
- * Summarize method endpoint information
- */ function createMethod(method, path, operation) {
-    return {
-        description: path.description,
-        summary: path.summary,
-        ...operation,
-        parameters: [
-            ...noRef(operation.parameters ?? []),
-            ...noRef(path.parameters ?? [])
-        ],
-        method: method.toUpperCase()
-    };
-}
-
 const methodKeys = [
     'get',
     'post',
@@ -32,38 +14,34 @@ const methodKeys = [
     'head',
     'put'
 ];
-/**
- * Build the route information of tags, use `.get('all')` to get all entries
- */ function buildRoutes(document) {
-    const map = new Map();
-    for (const [path, pathItem] of Object.entries(document.paths)){
+function getAPIPageItems(document) {
+    const result = {
+        webhooks: [],
+        operations: []
+    };
+    for (const [path, pathItem] of Object.entries(document.paths ?? {})){
         if (!pathItem) continue;
-        const methodMap = new Map();
         for (const methodKey of methodKeys){
-            const operation = pathItem[methodKey];
-            if (!operation) continue;
-            const info = createMethod(methodKey, pathItem, operation);
-            const tags = operation.tags ?? [];
-            for (const tag of [
-                ...tags,
-                'all'
-            ]){
-                const list = methodMap.get(tag) ?? [];
-                list.push(info);
-                methodMap.set(tag, list);
-            }
-        }
-        for (const [tag, methods] of methodMap.entries()){
-            const list = map.get(tag) ?? [];
-            list.push({
-                ...pathItem,
+            if (!pathItem[methodKey]) continue;
+            result.operations.push({
+                method: methodKey,
                 path,
-                methods
+                tags: pathItem[methodKey]?.tags
+            });
+        }
+    }
+    for (const [name, pathItem] of Object.entries(document.webhooks ?? {})){
+        if (!pathItem) continue;
+        for (const methodKey of methodKeys){
+            if (!pathItem[methodKey]) continue;
+            result.webhooks.push({
+                method: methodKey,
+                name,
+                tags: pathItem[methodKey]?.tags
             });
-            map.set(tag, list);
         }
     }
-    return map;
+    return result;
 }
 
 function idToTitle(id) {
@@ -83,10 +61,11 @@ function generateDocument(options) {
     const out = [];
     const extend = frontmatter?.(options.title, options.description, options.context);
     let meta;
-    if (options.context.type === 'operation') {
+    if (options.page.operations?.length === 1) {
+        const operation = options.page.operations[0];
         meta = {
-            method: options.context.endpoint.method,
-            route: options.context.route.path
+            method: operation.method.toUpperCase(),
+            route: operation.path
         };
     }
     const data = generateStaticData(options.dereferenced, options.page);
@@ -117,8 +96,8 @@ function generateStaticData(dereferenced, props) {
         headings: [],
         contents: []
     };
-    for (const item of props.operations){
-        const operation = dereferenced.paths[item.path]?.[item.method];
+    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);
@@ -144,107 +123,156 @@ function generateStaticData(dereferenced, props) {
     };
 }
 function pageContent(props) {
-    return `<APIPage document={${JSON.stringify(props.document)}} operations={${JSON.stringify(props.operations)}} hasHead={${JSON.stringify(props.hasHead)}} />`;
+    // 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)}} />`;
+}
+
+const cache = new Map();
+/**
+ * process & reference input document to a Fumadocs OpenAPI compatible format
+ */ async function processDocument(document, disableCache = false) {
+    const cached = !disableCache && typeof document === 'string' ? cache.get(document) : null;
+    if (cached) return cached;
+    let bundled = await Parser.bundle(document, {
+        mutateInputSchema: false
+    });
+    bundled = upgrade(bundled).specification;
+    const dereferenceMap = new Map();
+    const dereferenced = await Parser.dereference(bundled, {
+        mutateInputSchema: true,
+        dereference: {
+            onDereference ($ref, schema) {
+                dereferenceMap.set(schema, $ref);
+            }
+        }
+    });
+    const processed = {
+        document: dereferenced,
+        dereferenceMap
+    };
+    if (!disableCache && typeof document === 'string') {
+        cache.set(document, processed);
+    }
+    return processed;
 }
 
 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);
+    return await processDocument(// resolve paths
+    typeof pathOrDocument === 'string' && !pathOrDocument.startsWith('http://') && !pathOrDocument.startsWith('https://') ? resolve(options.cwd ?? process.cwd(), pathOrDocument) : pathOrDocument).then((res)=>res.document);
 }
 async function generateAll(pathOrDocument, options = {}) {
     const document = await dereference(pathOrDocument, options);
-    const routes = buildRoutes(document).get('all') ?? [];
-    const operations = [];
-    for (const route of routes){
-        for (const method of route.methods){
-            operations.push({
-                method: method.method.toLowerCase(),
-                path: route.path
-            });
-        }
-    }
+    const items = getAPIPageItems(document);
     return generateDocument({
         ...options,
         dereferenced: document,
         title: document.info.title,
         description: document.info.description,
         page: {
-            operations,
+            operations: items.operations,
+            webhooks: items.webhooks,
             hasHead: true,
             document: pathOrDocument
         },
         context: {
-            type: 'file',
-            routes
+            type: 'file'
         }
     });
 }
-async function generateOperations(pathOrDocument, options = {}) {
+async function generatePages(pathOrDocument, options = {}) {
     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({
+    const items = getAPIPageItems(document);
+    const result = [];
+    for (const item of items.operations){
+        const pathItem = document.paths?.[item.path];
+        if (!pathItem) continue;
+        const operation = pathItem[item.method];
+        if (!operation) continue;
+        result.push({
+            type: 'operation',
+            pathItem,
+            operation,
+            item,
+            content: generateDocument({
                 ...options,
                 page: {
                     operations: [
-                        {
-                            path: route.path,
-                            method: method.method.toLowerCase()
-                        }
+                        item
                     ],
                     hasHead: false,
                     document: pathOrDocument
                 },
                 dereferenced: document,
-                title: method.summary ?? idToTitle(method.operationId),
-                description: method.description,
+                title: operation.summary ?? pathItem.summary ?? idToTitle(operation.operationId ?? 'unknown'),
+                description: operation.description ?? pathItem.description,
                 context: {
-                    type: 'operation',
-                    endpoint: method,
-                    route
+                    type: 'operation'
                 }
-            });
-            return {
-                content,
-                route,
-                method
-            };
+            })
         });
-    });
+    }
+    for (const item of items.webhooks){
+        const pathItem = document.webhooks?.[item.name];
+        if (!pathItem) continue;
+        const operation = pathItem[item.method];
+        if (!operation) continue;
+        result.push({
+            type: 'webhook',
+            pathItem,
+            operation,
+            item,
+            content: generateDocument({
+                ...options,
+                page: {
+                    webhooks: [
+                        item
+                    ],
+                    hasHead: false,
+                    document: pathOrDocument
+                },
+                dereferenced: document,
+                title: operation.summary ?? pathItem.summary ?? idToTitle(item.name),
+                description: operation.description ?? pathItem.description,
+                context: {
+                    type: 'operation'
+                }
+            })
+        });
+    }
+    return result;
 }
 async function generateTags(pathOrDocument, options = {}) {
     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);
-        const operations = [];
-        for (const route of routes){
-            for (const method of route.methods){
-                operations.push({
-                    method: method.method.toLowerCase(),
-                    path: route.path
-                });
-            }
-        }
-        const displayName = info && 'x-displayName' in info && typeof info['x-displayName'] === 'string' ? info['x-displayName'] : idToTitle(tag);
+    if (!document.tags) return [];
+    const items = getAPIPageItems(document);
+    return document.tags.map((tag)=>{
+        const webhooks = items.webhooks.filter((v)=>v.tags && v.tags.includes(tag.name));
+        const operations = items.operations.filter((v)=>v.tags && v.tags.includes(tag.name));
+        const displayName = tag && 'x-displayName' in tag && typeof tag['x-displayName'] === 'string' ? tag['x-displayName'] : idToTitle(tag.name);
         return {
-            tag,
+            tag: tag.name,
             content: generateDocument({
                 ...options,
                 page: {
                     document: pathOrDocument,
                     operations,
+                    webhooks,
                     hasHead: true
                 },
                 dereferenced: document,
                 title: displayName,
-                description: info?.description,
+                description: tag?.description,
                 context: {
                     type: 'tag',
-                    tag: info,
-                    routes
+                    tag
                 }
             })
         };
@@ -272,7 +300,28 @@ async function generateFiles(options) {
         }),
         ...urlInputs
     ];
-    await Promise.all(resolvedInputs.map(async (pathOrUrl)=>{
+    function getOutputPaths(name, result) {
+        const outPaths = [];
+        if (groupBy === 'tag') {
+            const tags = result.operation.tags;
+            if (tags && tags.length > 0) {
+                for (const tag of tags){
+                    outPaths.push(join(outputDir, getFilename(tag), `${getFilename(name)}.mdx`));
+                }
+            } else {
+                outPaths.push(result.type === 'operation' ? join(outputDir, `${getFilename(name)}.mdx`) : join(outputDir, 'webhooks', `${getFilename(name)}.mdx`));
+            }
+        }
+        if (groupBy === 'route') {
+            const dir = result.pathItem.summary ? getFilename(result.pathItem.summary) : getFilenameFromRoute(result.type === 'operation' ? result.item.path : result.item.name);
+            outPaths.push(join(outputDir, dir, `${getFilename(name)}.mdx`));
+        }
+        if (groupBy === 'none') {
+            outPaths.push(join(outputDir, `${getFilename(name)}.mdx`));
+        }
+        return outPaths;
+    }
+    async function generateFromDocument(pathOrUrl) {
         if (per === 'file') {
             let filename = isUrl(pathOrUrl) ? 'index' : parse(pathOrUrl).name;
             if (nameFn) filename = nameFn('file', filename);
@@ -280,49 +329,41 @@ async function generateFiles(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(pathOrUrl, options);
-            await Promise.all(results.map(async (result)=>{
-                const outPaths = new Array();
-                if (!result.method.operationId) return;
-                const id = result.method.operationId.split('.').at(-1) ?? result.method.operationId;
-                if (groupBy === 'tag' && result.method.tags && result.method.tags.length > 0) {
-                    for (const tag of result.method.tags){
-                        outPaths.push(join(outputDir, getFilename(tag), `${getFilename(id)}.mdx`));
-                    }
-                } else if (groupBy === 'route') {
-                    const outPath = join(outputDir, result.route.summary ? getFilename(result.route.summary) : getFilenameFromRoute(result.route.path), `${getFilename(id)}.mdx`);
-                    const metaFile = join(dirname(outPath), 'meta.json');
-                    if (result.route.summary && !metaFiles.has(metaFile)) {
+            const results = await generatePages(pathOrUrl, options);
+            for (const result of results){
+                let name = result.type === 'operation' ? result.operation.operationId : result.item.name;
+                if (!name) return;
+                name = name.split('.').at(-1) ?? name;
+                for (const outPath of getOutputPaths(name, result)){
+                    await write(outPath, result.content);
+                    console.log(`Generated: ${outPath}`);
+                    if (groupBy === 'route') {
+                        const metaFile = join(dirname(outPath), 'meta.json');
+                        if (!result.pathItem.summary || metaFiles.has(metaFile)) continue;
                         metaFiles.add(metaFile);
                         await write(metaFile, JSON.stringify({
-                            title: result.route.summary
-                        }));
+                            title: result.pathItem.summary
+                        }, null, 2));
                         console.log(`Generated Meta: ${metaFile}`);
                     }
-                    outPaths.push(outPath);
-                } else {
-                    outPaths.push(join(outputDir, `${getFilename(id)}.mdx`));
-                }
-                for (const outPath of outPaths){
-                    await write(outPath, result.content);
-                    console.log(`Generated: ${outPath}`);
                 }
-            }));
-            return;
+            }
         }
-        const results = await generateTags(pathOrUrl, options);
-        for (const result of results){
-            let tagName = result.tag;
-            tagName = nameFn?.('tag', tagName) ?? getFilename(tagName);
-            const outPath = join(outputDir, `${tagName}.mdx`);
-            await write(outPath, result.content);
-            console.log(`Generated: ${outPath}`);
+        if (per === 'tag') {
+            const results = await generateTags(pathOrUrl, options);
+            for (const result of results){
+                let tagName = result.tag;
+                tagName = nameFn?.('tag', tagName) ?? getFilename(tagName);
+                const outPath = join(outputDir, `${tagName}.mdx`);
+                await write(outPath, result.content);
+                console.log(`Generated: ${outPath}`);
+            }
         }
-    }));
+    }
+    await Promise.all(resolvedInputs.map(generateFromDocument));
 }
 function isUrl(input) {
     return input.startsWith('https://') || input.startsWith('http://');
@@ -340,4 +381,4 @@ async function write(path, content) {
     await writeFile(path, content);
 }
 
-export { generateAll, generateFiles, generateOperations, generateTags };
+export { generateAll, generateFiles, generatePages, generateTags };