fumadocs-openapi 5.11.8 → 6.0.0

package/dist/index.d.ts

@@ -3,64 +3,10 @@ import Slugger from 'github-slugger';
 import { ComponentType, ReactNode } from 'react';
 import { CodeToHastOptionsCommon, CodeOptionsThemes, BuiltinTheme } from 'shiki';
 
-interface BaseRequestField {
-    name: string;
-    description?: string;
-}
-interface BaseSchema {
-    description?: string;
-    isRequired: boolean;
-}
-type PrimitiveRequestField = BaseRequestField & PrimitiveSchema;
-interface PrimitiveSchema extends BaseSchema {
-    type: 'boolean' | 'string' | 'number';
-    defaultValue: string;
-}
-interface ReferenceSchema extends BaseSchema {
-    type: 'ref';
-    schema: string;
-}
-interface ArraySchema extends BaseSchema {
-    type: 'array';
-    /**
-     * Reference to item schema or the schema
-     */
-    items: string | RequestSchema;
-}
-interface FileSchema extends BaseSchema {
-    type: 'file';
-}
-interface ObjectSchema extends BaseSchema {
-    type: 'object';
-    properties: Record<string, ReferenceSchema>;
-    /**
-     * Reference to schema, or true if it's `any`
-     */
-    additionalProperties?: boolean | string;
-}
-interface SwitcherSchema extends BaseSchema {
-    type: 'switcher';
-    items: Record<string, ReferenceSchema | RequestSchema>;
-}
-interface NullSchema extends BaseSchema {
-    type: 'null';
-}
-type RequestSchema = PrimitiveSchema | ArraySchema | ObjectSchema | SwitcherSchema | NullSchema | FileSchema;
-interface APIPlaygroundProps {
-    route: string;
-    method: string;
-    authorization?: PrimitiveRequestField & {
-        authType: string;
-    };
-    path?: PrimitiveRequestField[];
-    query?: PrimitiveRequestField[];
-    header?: PrimitiveRequestField[];
-    body?: RequestSchema & {
-        mediaType: string;
-    };
-    schemas: Record<string, RequestSchema>;
-    proxyUrl?: string;
-}
+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;
 
 interface ResponsesProps {
     items: string[];
@@ -127,14 +73,13 @@ interface Renderer {
      */
     ObjectCollapsible: ComponentType<ObjectCollapsibleProps>;
     Property: ComponentType<PropertyProps>;
-    APIPlayground: ComponentType<APIPlaygroundProps>;
+    APIPlayground: ComponentType<{
+        path: string;
+        method: MethodInformation;
+        ctx: RenderContext;
+    }>;
 }
 
-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
  */
@@ -170,6 +115,13 @@ interface CodeSample {
     source: string | ((endpoint: EndpointSample) => string | undefined) | false;
 }
 
+type DocumentInput = string | OpenAPIV3_1.Document | OpenAPIV3.Document;
+type ProcessedDocument = {
+    document: NoReference<Document>;
+    dereferenceMap: DereferenceMap;
+    downloaded: Document;
+};
+
 type Document = OpenAPIV3_1.Document;
 type OperationObject = OpenAPIV3_1.OperationObject;
 type ParameterObject = OpenAPIV3_1.ParameterObject;
@@ -194,14 +146,13 @@ interface RenderContext {
      */
     proxyUrl?: string;
     renderer: Renderer;
-    /**
-     * dereferenced schema
-     */
-    document: NoReference<Document>;
     baseUrl: string;
     servers: ServerObject[];
     slugger: Slugger;
-    dereferenceMap: DereferenceMap;
+    /**
+     * dereferenced schema
+     */
+    schema: ProcessedDocument;
     /**
      * Generate TypeScript definitions from response schema.
      *
@@ -222,8 +173,6 @@ interface RenderContext {
     showResponseSchema?: boolean;
 }
 
-type DocumentInput = string | OpenAPIV3_1.Document | OpenAPIV3.Document;
-
 interface WebhookItem {
     name: string;
     method: OpenAPIV3_1.HttpMethods;

package/dist/index.js

@@ -158,7 +158,8 @@ const cache = new Map();
     });
     const processed = {
         document: dereferenced,
-        dereferenceMap
+        dereferenceMap,
+        downloaded: loaded.specification
     };
     if (!disableCache && typeof document === 'string') {
         cache.set(document, processed);
@@ -302,24 +303,28 @@ async function generateFiles(options) {
         }),
         ...urlInputs
     ];
-    function getOutputPaths(name, result) {
+    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), `${getFilename(name)}.mdx`));
+                    outPaths.push(join(outputDir, getFilename(tag), `${file}.mdx`));
                 }
             } else {
-                outPaths.push(result.type === 'operation' ? join(outputDir, `${getFilename(name)}.mdx`) : join(outputDir, 'webhooks', `${getFilename(name)}.mdx`));
+                outPaths.push(result.type === 'operation' ? join(outputDir, `${file}.mdx`) : join(outputDir, 'webhooks', `${file}.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`));
+        if (groupBy === 'route' || groupBy === 'none') {
+            outPaths.push(join(outputDir, `${file}.mdx`));
         }
         return outPaths;
     }
@@ -336,19 +341,17 @@ async function generateFiles(options) {
             const metaFiles = new Set();
             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)){
+                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, JSON.stringify({
-                            title: result.pathItem.summary
-                        }, null, 2));
+                        await write(metaFile, meta);
                         console.log(`Generated Meta: ${metaFile}`);
                     }
                 }
@@ -370,7 +373,7 @@ async function generateFiles(options) {
 function isUrl(input) {
     return input.startsWith('https://') || input.startsWith('http://');
 }
-function getFilenameFromRoute(path) {
+function getOutputPathFromRoute(path) {
     return path.replaceAll('.', '/').split('/').filter((v)=>!v.startsWith('{') && !v.endsWith('}')).at(-1) ?? '';
 }
 function getFilename(s) {

package/dist/scalar/client-client-DgnHaOQ3.js

@@ -0,0 +1,93 @@
+'use client';
+import { jsx, jsxs } from 'react/jsx-runtime';
+import { cn } from 'fumadocs-ui/components/api';
+import { buttonVariants } from 'fumadocs-ui/components/ui/button';
+import { ApiClientModalProvider, useApiClientModal } from '@scalar/api-client-react';
+import { cva } from 'class-variance-authority';
+import { useTheme } from 'next-themes';
+import { useState, useEffect } from 'react';
+
+const variants = cva('font-mono font-medium', {
+    variants: {
+        color: {
+            green: 'text-green-600 dark:text-green-400',
+            yellow: 'text-yellow-600 dark:text-yellow-400',
+            red: 'text-red-600 dark:text-red-400',
+            blue: 'text-blue-600 dark:text-blue-400',
+            orange: 'text-orange-600 dark:text-orange-400'
+        }
+    }
+});
+function getBadgeColor(method) {
+    switch(method.toUpperCase()){
+        case 'PUT':
+            return 'yellow';
+        case 'PATCH':
+            return 'orange';
+        case 'POST':
+            return 'blue';
+        case 'DELETE':
+            return 'red';
+        default:
+            return 'green';
+    }
+}
+function MethodLabel({ children, ...props }) {
+    return /*#__PURE__*/ jsx("span", {
+        ...props,
+        className: cn(variants({
+            color: getBadgeColor(children)
+        }), props.className),
+        children: children.toUpperCase()
+    });
+}
+
+function ScalarPlayground({ path, method, spec }) {
+    const { resolvedTheme } = useTheme();
+    const [mounted, setMounted] = useState(false);
+    useEffect(()=>{
+        setMounted(true);
+    }, []);
+    return /*#__PURE__*/ jsxs("div", {
+        className: cn('flex flex-row items-center gap-2.5 p-3 rounded-xl border bg-fd-card text-fd-card-foreground not-prose', mounted ? `${resolvedTheme}-mode` : null),
+        children: [
+            /*#__PURE__*/ jsx(MethodLabel, {
+                className: "text-xs",
+                children: method
+            }),
+            /*#__PURE__*/ jsx("code", {
+                className: "flex-1 overflow-auto text-nowrap text-[13px] text-fd-muted-foreground",
+                children: path
+            }),
+            /*#__PURE__*/ jsx(ApiClientModalProvider, {
+                configuration: {
+                    themeId: 'moon',
+                    spec: {
+                        content: spec
+                    }
+                },
+                children: /*#__PURE__*/ jsx(Trigger, {
+                    path: path,
+                    method: method
+                })
+            })
+        ]
+    });
+}
+function Trigger({ path, method }) {
+    const client = useApiClientModal();
+    return /*#__PURE__*/ jsx("button", {
+        type: "submit",
+        className: cn(buttonVariants({
+            color: 'primary',
+            size: 'sm'
+        }), 'px-3 py-1.5'),
+        onClick: ()=>client?.open({
+                path,
+                method
+            }),
+        children: "Test"
+    });
+}
+
+export { ScalarPlayground as default };

package/dist/scalar/index.d.ts

@@ -0,0 +1,176 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { OpenAPIV3_1 } from 'openapi-types';
+import Slugger from 'github-slugger';
+import { ComponentType, ReactNode } from 'react';
+import { CodeToHastOptionsCommon, CodeOptionsThemes, BuiltinTheme } from 'shiki';
+
+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;
+
+interface ResponsesProps {
+    items: string[];
+    children: ReactNode;
+}
+interface ResponseProps {
+    value: string;
+    children: ReactNode;
+}
+interface APIInfoProps {
+    method: string;
+    route: string;
+    head: ReactNode;
+    children: ReactNode;
+}
+interface PropertyProps {
+    name: string;
+    type: string;
+    required?: boolean;
+    deprecated?: boolean;
+    children?: ReactNode;
+}
+interface ObjectCollapsibleProps {
+    name: string;
+    children: ReactNode;
+}
+interface RequestProps {
+    language: string;
+    name: string;
+    code: string;
+}
+interface ResponseTypeProps {
+    lang: string;
+    code: string;
+    label: string;
+}
+interface RootProps {
+    baseUrl?: string;
+    servers: ServerObject[];
+    children: ReactNode;
+}
+interface Renderer {
+    Root: ComponentType<RootProps>;
+    API: ComponentType<{
+        children: ReactNode;
+    }>;
+    APIInfo: ComponentType<APIInfoProps>;
+    APIExample: ComponentType<{
+        children: ReactNode;
+    }>;
+    Responses: ComponentType<ResponsesProps>;
+    Response: ComponentType<ResponseProps>;
+    Requests: ComponentType<{
+        items: string[];
+        children: ReactNode;
+    }>;
+    Request: ComponentType<RequestProps>;
+    ResponseTypes: ComponentType<{
+        children: ReactNode;
+    }>;
+    ResponseType: ComponentType<ResponseTypeProps>;
+    /**
+     * Collapsible to show object schemas
+     */
+    ObjectCollapsible: ComponentType<ObjectCollapsibleProps>;
+    Property: ComponentType<PropertyProps>;
+    APIPlayground: ComponentType<{
+        path: string;
+        method: MethodInformation;
+        ctx: RenderContext;
+    }>;
+}
+
+/**
+ * Sample info of endpoint
+ */
+interface EndpointSample {
+    /**
+     * Request URL, including path and query parameters
+     */
+    url: string;
+    method: string;
+    body?: {
+        schema: ParsedSchema;
+        mediaType: string;
+        sample: unknown;
+    };
+    responses: Record<string, ResponseSample>;
+    parameters: ParameterSample[];
+}
+interface ResponseSample {
+    mediaType: string;
+    sample: unknown;
+    schema: ParsedSchema;
+}
+interface ParameterSample {
+    name: string;
+    in: string;
+    schema: ParsedSchema;
+    sample: unknown;
+}
+
+interface CodeSample {
+    lang: string;
+    label: string;
+    source: string | ((endpoint: EndpointSample) => string | undefined) | false;
+}
+
+type ProcessedDocument = {
+    document: NoReference<Document>;
+    dereferenceMap: DereferenceMap;
+    downloaded: Document;
+};
+
+type Document = OpenAPIV3_1.Document;
+type OperationObject = OpenAPIV3_1.OperationObject;
+type ReferenceObject = OpenAPIV3_1.ReferenceObject;
+type ServerObject = NoReference<OpenAPIV3_1.ServerObject>;
+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 {
+    /**
+     * The url of proxy to avoid CORS issues
+     */
+    proxyUrl?: string;
+    renderer: Renderer;
+    baseUrl: string;
+    servers: ServerObject[];
+    slugger: Slugger;
+    /**
+     * dereferenced schema
+     */
+    schema: ProcessedDocument;
+    /**
+     * Generate TypeScript definitions from response schema.
+     *
+     * Pass `false` to disable it.
+     *
+     * @param endpoint - the API endpoint
+     * @param code - status code
+     */
+    generateTypeScriptSchema?: ((endpoint: EndpointSample, code: string) => Awaitable<string>) | false;
+    /**
+     * Generate code samples for endpoint.
+     */
+    generateCodeSamples?: (endpoint: EndpointSample) => Awaitable<CodeSample[]>;
+    shikiOptions?: Omit<CodeToHastOptionsCommon, 'lang'> & CodeOptionsThemes<BuiltinTheme>;
+    /**
+     * Show full response schema instead of only example response & Typescript definitions
+     */
+    showResponseSchema?: boolean;
+}
+
+declare function APIPlayground({ path, method, ctx, }: {
+    path: string;
+    method: MethodInformation;
+    ctx: RenderContext;
+}): react_jsx_runtime.JSX.Element;
+
+export { APIPlayground };

package/dist/scalar/index.js

@@ -0,0 +1,13 @@
+import { jsx } from 'react/jsx-runtime';
+import dynamic from 'next/dynamic';
+
+const Client = dynamic(()=>import('./client-client-DgnHaOQ3.js'));
+function APIPlayground({ path, method, ctx }) {
+    return /*#__PURE__*/ jsx(Client, {
+        method: method.method,
+        path: path,
+        spec: ctx.schema.downloaded
+    });
+}
+
+export { APIPlayground };

package/dist/server/index.d.ts

@@ -5,64 +5,10 @@ import { CodeToHastOptionsCommon, CodeOptionsThemes, BuiltinTheme } from 'shiki'
 import { NextRequest } from 'next/server';
 import { BuildPageTreeOptions } from 'fumadocs-core/source';
 
-interface BaseRequestField {
-    name: string;
-    description?: string;
-}
-interface BaseSchema {
-    description?: string;
-    isRequired: boolean;
-}
-type PrimitiveRequestField = BaseRequestField & PrimitiveSchema;
-interface PrimitiveSchema extends BaseSchema {
-    type: 'boolean' | 'string' | 'number';
-    defaultValue: string;
-}
-interface ReferenceSchema extends BaseSchema {
-    type: 'ref';
-    schema: string;
-}
-interface ArraySchema extends BaseSchema {
-    type: 'array';
-    /**
-     * Reference to item schema or the schema
-     */
-    items: string | RequestSchema;
-}
-interface FileSchema extends BaseSchema {
-    type: 'file';
-}
-interface ObjectSchema extends BaseSchema {
-    type: 'object';
-    properties: Record<string, ReferenceSchema>;
-    /**
-     * Reference to schema, or true if it's `any`
-     */
-    additionalProperties?: boolean | string;
-}
-interface SwitcherSchema extends BaseSchema {
-    type: 'switcher';
-    items: Record<string, ReferenceSchema | RequestSchema>;
-}
-interface NullSchema extends BaseSchema {
-    type: 'null';
-}
-type RequestSchema = PrimitiveSchema | ArraySchema | ObjectSchema | SwitcherSchema | NullSchema | FileSchema;
-interface APIPlaygroundProps {
-    route: string;
-    method: string;
-    authorization?: PrimitiveRequestField & {
-        authType: string;
-    };
-    path?: PrimitiveRequestField[];
-    query?: PrimitiveRequestField[];
-    header?: PrimitiveRequestField[];
-    body?: RequestSchema & {
-        mediaType: string;
-    };
-    schemas: Record<string, RequestSchema>;
-    proxyUrl?: string;
-}
+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;
 
 interface ResponsesProps {
     items: string[];
@@ -129,14 +75,13 @@ interface Renderer {
      */
     ObjectCollapsible: ComponentType<ObjectCollapsibleProps>;
     Property: ComponentType<PropertyProps>;
-    APIPlayground: ComponentType<APIPlaygroundProps>;
+    APIPlayground: ComponentType<{
+        path: string;
+        method: MethodInformation;
+        ctx: RenderContext;
+    }>;
 }
 
-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
  */
@@ -172,9 +117,20 @@ interface CodeSample {
     source: string | ((endpoint: EndpointSample) => string | undefined) | false;
 }
 
+type DocumentInput = string | OpenAPIV3_1.Document | OpenAPIV3.Document;
+type ProcessedDocument = {
+    document: NoReference<Document>;
+    dereferenceMap: DereferenceMap;
+    downloaded: Document;
+};
+
 type Document = OpenAPIV3_1.Document;
+type OperationObject = OpenAPIV3_1.OperationObject;
 type ReferenceObject = OpenAPIV3_1.ReferenceObject;
 type ServerObject = NoReference<OpenAPIV3_1.ServerObject>;
+type MethodInformation = NoReference<OperationObject> & {
+    method: string;
+};
 type Awaitable<T> = T | Promise<T>;
 /**
  * Dereferenced value and its original `$ref` value
@@ -186,14 +142,13 @@ interface RenderContext {
      */
     proxyUrl?: string;
     renderer: Renderer;
-    /**
-     * dereferenced schema
-     */
-    document: NoReference<Document>;
     baseUrl: string;
     servers: ServerObject[];
     slugger: Slugger;
-    dereferenceMap: DereferenceMap;
+    /**
+     * dereferenced schema
+     */
+    schema: ProcessedDocument;
     /**
      * Generate TypeScript definitions from response schema.
      *
@@ -214,8 +169,6 @@ interface RenderContext {
     showResponseSchema?: boolean;
 }
 
-type DocumentInput = string | OpenAPIV3_1.Document | OpenAPIV3.Document;
-
 type ApiPageContextProps = Pick<Partial<RenderContext>, 'shikiOptions' | 'generateTypeScriptSchema' | 'generateCodeSamples' | 'proxyUrl' | 'showResponseSchema'>;
 interface ApiPageProps extends ApiPageContextProps {
     document: DocumentInput;