fumadocs-openapi 6.0.0 → 6.0.2

package/dist/index.js

@@ -1,389 +1,3 @@
-import { resolve, join, parse, dirname } from 'node:path';
-import { dump } from 'js-yaml';
-import Slugger from 'github-slugger';
-import { load, upgrade, dereference as dereference$1 } from '@scalar/openapi-parser';
-import { fetchUrls } from '@scalar/openapi-parser/plugins/fetch-urls';
-import { readFiles } from '@scalar/openapi-parser/plugins/read-files';
-import { mkdir, writeFile } from 'node:fs/promises';
-import fg from 'fast-glob';
-
-const methodKeys = [
-    'get',
-    'post',
-    'patch',
-    'delete',
-    'head',
-    'put'
-];
-function getAPIPageItems(document) {
-    const result = {
-        webhooks: [],
-        operations: []
-    };
-    for (const [path, pathItem] of Object.entries(document.paths ?? {})){
-        if (!pathItem) continue;
-        for (const methodKey of methodKeys){
-            if (!pathItem[methodKey]) continue;
-            result.operations.push({
-                method: methodKey,
-                path,
-                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
-            });
-        }
-    }
-    return result;
-}
-
-function idToTitle(id) {
-    let result = [];
-    for (const c of id){
-        if (result.length === 0) result.push(c.toLocaleUpperCase());
-        else if (c === '.') result = [];
-        else if (/^[A-Z]$/.test(c) && result.at(-1) !== ' ') result.push(' ', c);
-        else if (c === '-') result.push(' ');
-        else result.push(c);
-    }
-    return result.join('');
-}
-
-function generateDocument(options) {
-    const { frontmatter, includeDescription = false } = options;
-    const out = [];
-    const extend = frontmatter?.(options.title, options.description, options.context);
-    let meta;
-    if (options.page.operations?.length === 1) {
-        const operation = options.page.operations[0];
-        meta = {
-            method: operation.method.toUpperCase(),
-            route: operation.path
-        };
-    }
-    const data = generateStaticData(options.dereferenced, options.page);
-    const banner = dump({
-        title: options.title,
-        description: options.description,
-        full: true,
-        ...extend,
-        _openapi: {
-            ...meta,
-            ...data,
-            ...extend?._openapi
-        }
-    }).trim();
-    if (banner.length > 0) out.push(`---\n${banner}\n---`);
-    const imports = options.imports?.map((item)=>`import { ${item.names.join(', ')} } from ${JSON.stringify(item.from)};`).join('\n');
-    if (imports) {
-        out.push(imports);
-    }
-    if (options.description && includeDescription) out.push(options.description);
-    out.push(pageContent(options.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)}} />`;
-}
-
-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;
-    const dereferenceMap = new Map();
-    const loaded = await load(document, {
-        plugins: [
-            readFiles(),
-            fetchUrls()
-        ]
-    });
-    // upgrade
-    loaded.specification = upgrade(loaded.specification).specification;
-    const { schema: dereferenced } = await dereference$1(loaded.filesystem, {
-        onDereference ({ ref, schema }) {
-            dereferenceMap.set(schema, ref);
-        }
-    });
-    const processed = {
-        document: dereferenced,
-        dereferenceMap,
-        downloaded: loaded.specification
-    };
-    if (!disableCache && typeof document === 'string') {
-        cache.set(document, processed);
-    }
-    return processed;
-}
-
-async function dereference(pathOrDocument, options) {
-    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 items = getAPIPageItems(document);
-    return generateDocument({
-        ...options,
-        dereferenced: document,
-        title: document.info.title,
-        description: document.info.description,
-        page: {
-            operations: items.operations,
-            webhooks: items.webhooks,
-            hasHead: true,
-            document: pathOrDocument
-        },
-        context: {
-            type: 'file'
-        }
-    });
-}
-async function generatePages(pathOrDocument, options = {}) {
-    const document = await dereference(pathOrDocument, options);
-    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: [
-                        item
-                    ],
-                    hasHead: false,
-                    document: pathOrDocument
-                },
-                dereferenced: document,
-                title: operation.summary ?? pathItem.summary ?? idToTitle(operation.operationId ?? 'unknown'),
-                description: operation.description ?? pathItem.description,
-                context: {
-                    type: 'operation'
-                }
-            })
-        });
-    }
-    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);
-    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.name,
-            content: generateDocument({
-                ...options,
-                page: {
-                    document: pathOrDocument,
-                    operations,
-                    webhooks,
-                    hasHead: true
-                },
-                dereferenced: document,
-                title: displayName,
-                description: tag?.description,
-                context: {
-                    type: 'tag',
-                    tag
-                }
-            })
-        };
-    });
-}
-
-async function generateFiles(options) {
-    const { input, output, name: nameFn, per = 'operation', groupBy = 'none', cwd = process.cwd() } = options;
-    const outputDir = join(cwd, output);
-    const urlInputs = [];
-    const fileInputs = [];
-    for (const v of typeof input === 'string' ? [
-        input
-    ] : input){
-        if (isUrl(v)) {
-            urlInputs.push(v);
-        } else {
-            fileInputs.push(v);
-        }
-    }
-    const resolvedInputs = [
-        ...await fg.glob(fileInputs, {
-            cwd,
-            absolute: false
-        }),
-        ...urlInputs
-    ];
-    function getOutputPaths(result) {
-        let file;
-        if (result.pathItem.summary) {
-            file = getFilename(result.pathItem.summary);
-        } else if (result.type === 'operation') {
-            file = result.operation.operationId ? getFilename(result.operation.operationId) : join(getOutputPathFromRoute(result.item.path), result.item.method.toLowerCase());
-        } else {
-            file = getFilename(result.item.name);
-        }
-        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), `${file}.mdx`));
-                }
-            } else {
-                outPaths.push(result.type === 'operation' ? join(outputDir, `${file}.mdx`) : join(outputDir, 'webhooks', `${file}.mdx`));
-            }
-        }
-        if (groupBy === 'route' || groupBy === 'none') {
-            outPaths.push(join(outputDir, `${file}.mdx`));
-        }
-        return outPaths;
-    }
-    async function generateFromDocument(pathOrUrl) {
-        if (per === 'file') {
-            let filename = isUrl(pathOrUrl) ? 'index' : parse(pathOrUrl).name;
-            if (nameFn) filename = nameFn('file', filename);
-            const outPath = join(outputDir, `${filename}.mdx`);
-            const result = await generateAll(pathOrUrl, options);
-            await write(outPath, result);
-            console.log(`Generated: ${outPath}`);
-        }
-        if (per === 'operation') {
-            const metaFiles = new Set();
-            const results = await generatePages(pathOrUrl, options);
-            for (const result of results){
-                const meta = JSON.stringify({
-                    title: result.pathItem.summary
-                }, null, 2);
-                for (const outPath of getOutputPaths(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, meta);
-                        console.log(`Generated Meta: ${metaFile}`);
-                    }
-                }
-            }
-        }
-        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://');
-}
-function getOutputPathFromRoute(path) {
-    return path.replaceAll('.', '/').split('/').filter((v)=>!v.startsWith('{') && !v.endsWith('}')).at(-1) ?? '';
-}
-function getFilename(s) {
-    return s.replace(/[A-Z]/g, (match, idx)=>idx === 0 ? match : `-${match.toLowerCase()}`).replace(/\s+/g, '-').toLowerCase();
-}
-async function write(path, content) {
-    await mkdir(dirname(path), {
-        recursive: true
-    });
-    await writeFile(path, content);
-}
-
-export { generateAll, generateFiles, generatePages, generateTags };
+export * from './generate';
+export * from './generate-file';
+export * from './types';

package/dist/render/codeblock.d.ts

@@ -0,0 +1,9 @@
+import { type HTMLAttributes } from 'react';
+import type { RenderContext } from '../types';
+export type CodeBlockProps = HTMLAttributes<HTMLPreElement> & {
+    code: string;
+    lang: string;
+    options?: RenderContext['shikiOptions'];
+};
+export declare function CodeBlock({ code, lang, options, ...rest }: CodeBlockProps): Promise<React.ReactElement>;
+//# sourceMappingURL=codeblock.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"codeblock.d.ts","sourceRoot":"","sources":["../../src/render/codeblock.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,OAAO,CAAC;AAE5C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAG7C,MAAM,MAAM,cAAc,GAAG,cAAc,CAAC,cAAc,CAAC,GAAG;IAC5D,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,aAAa,CAAC,cAAc,CAAC,CAAC;CACzC,CAAC;AAEF,wBAAsB,SAAS,CAAC,EAC9B,IAAI,EACJ,IAAI,EACJ,OAAO,EACP,GAAG,IAAI,EACR,EAAE,cAAc,GAAG,OAAO,CAAC,KAAK,CAAC,YAAY,CAAC,CAU9C"}

package/dist/render/codeblock.js

@@ -0,0 +1,13 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import * as Base from 'fumadocs-ui/components/codeblock';
+import { highlight } from 'fumadocs-core/server';
+export async function CodeBlock({ code, lang, options, ...rest }) {
+    const rendered = await highlight(code, {
+        lang,
+        ...options,
+        components: {
+            pre: (props) => _jsx(Base.Pre, { ...props, ...rest }),
+        },
+    });
+    return _jsx(Base.CodeBlock, { className: "my-0", children: rendered });
+}

package/dist/render/heading.d.ts

@@ -0,0 +1,4 @@
+import type { ReactNode } from 'react';
+import type { RenderContext } from '../types';
+export declare function heading(depth: number, child: string, ctx: RenderContext): ReactNode;
+//# sourceMappingURL=heading.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"heading.d.ts","sourceRoot":"","sources":["../../src/render/heading.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAEvC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAE7C,wBAAgB,OAAO,CACrB,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,aAAa,GACjB,SAAS,CAQX"}

package/dist/render/heading.js

@@ -0,0 +1,6 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Heading } from 'fumadocs-ui/components/heading';
+export function heading(depth, child, ctx) {
+    const id = ctx.slugger.slug(child);
+    return (_jsx(Heading, { id: id, as: `h${depth.toString()}`, children: child.trim() }, id));
+}

package/dist/render/markdown.d.ts

@@ -0,0 +1,5 @@
+import { type ReactElement } from 'react';
+export declare function Markdown({ text, }: {
+    text: string;
+}): Promise<ReactElement>;
+//# sourceMappingURL=markdown.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"markdown.d.ts","sourceRoot":"","sources":["../../src/render/markdown.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,YAAY,EAAE,MAAM,OAAO,CAAC;AAsB1C,wBAAsB,QAAQ,CAAC,EAC7B,IAAI,GACL,EAAE;IACD,IAAI,EAAE,MAAM,CAAC;CACd,GAAG,OAAO,CAAC,YAAY,CAAC,CAWxB"}

package/dist/render/markdown.js

@@ -0,0 +1,25 @@
+import { rehypeCode, remarkGfm, remarkImage, } from 'fumadocs-core/mdx-plugins';
+import defaultMdxComponents from 'fumadocs-ui/mdx';
+import { remark } from 'remark';
+import remarkRehype from 'remark-rehype';
+import { toJsxRuntime } from 'hast-util-to-jsx-runtime';
+import { jsx, jsxs, Fragment } from 'react/jsx-runtime';
+const processor = remark()
+    .use(remarkGfm)
+    .use(remarkImage, { useImport: false })
+    .use(remarkRehype)
+    .use(rehypeCode, {
+    langs: [],
+    lazy: true,
+});
+export async function Markdown({ text, }) {
+    const nodes = processor.parse({ value: text });
+    const hast = await processor.run(nodes);
+    return toJsxRuntime(hast, {
+        development: false,
+        jsx: jsx,
+        jsxs: jsxs,
+        Fragment,
+        components: defaultMdxComponents,
+    });
+}

package/dist/render/operation.d.ts

@@ -0,0 +1,17 @@
+import { type ReactElement } from 'react';
+import { type EndpointSample } from '../utils/generate-sample';
+import type { MethodInformation, RenderContext } from '../types';
+export interface CodeSample {
+    lang: string;
+    label: string;
+    source: string | ((endpoint: EndpointSample) => string | undefined) | false;
+}
+export declare function Operation({ type, path, method, ctx, hasHead, headingLevel, }: {
+    type?: 'webhook' | 'operation';
+    path: string;
+    method: MethodInformation;
+    ctx: RenderContext;
+    hasHead?: boolean;
+    headingLevel?: number;
+}): ReactElement;
+//# sourceMappingURL=operation.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"operation.d.ts","sourceRoot":"","sources":["../../src/render/operation.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAY,KAAK,YAAY,EAAkB,MAAM,OAAO,CAAC;AACpE,OAAO,EAAkB,KAAK,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAK9E,OAAO,KAAK,EAEV,iBAAiB,EAEjB,aAAa,EAEd,MAAM,SAAS,CAAC;AAgBjB,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,GAAG,CAAC,CAAC,QAAQ,EAAE,cAAc,KAAK,MAAM,GAAG,SAAS,CAAC,GAAG,KAAK,CAAC;CAC7E;AAQD,wBAAgB,SAAS,CAAC,EACxB,IAAkB,EAClB,IAAI,EACJ,MAAM,EACN,GAAG,EACH,OAAO,EACP,YAAgB,GACjB,EAAE;IACD,IAAI,CAAC,EAAE,SAAS,GAAG,WAAW,CAAC;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,iBAAiB,CAAC;IAC1B,GAAG,EAAE,aAAa,CAAC;IAEnB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,GAAG,YAAY,CAoLf"}