fumadocs-openapi 5.2.1 → 5.3.0

package/dist/index.js

@@ -5,10 +5,21 @@ import Slugger from 'github-slugger';
 import { mkdir, writeFile } from 'node:fs/promises';
 import fg from 'fast-glob';
 
-function createMethod(method, operation) {
+function noRef(v) {
+    return v;
+}
+
+/**
+ * Summarize method endpoint information
+ */ function createMethod(method, path, operation) {
     return {
+        description: path.description,
+        summary: path.summary,
         ...operation,
-        parameters: operation.parameters ?? [],
+        parameters: [
+            ...noRef(operation.parameters ?? []),
+            ...noRef(path.parameters ?? [])
+        ],
         method: method.toUpperCase()
     };
 }
@@ -25,13 +36,13 @@ const methodKeys = [
  * Build the route information of tags, use `.get('all')` to get all entries
  */ function buildRoutes(document) {
     const map = new Map();
-    for (const [path, value] of Object.entries(document.paths)){
-        if (!value) continue;
+    for (const [path, pathItem] of Object.entries(document.paths)){
+        if (!pathItem) continue;
         const methodMap = new Map();
         for (const methodKey of methodKeys){
-            const operation = value[methodKey];
+            const operation = pathItem[methodKey];
             if (!operation) continue;
-            const info = createMethod(methodKey, operation);
+            const info = createMethod(methodKey, pathItem, operation);
             const tags = operation.tags ?? [];
             for (const tag of [
                 ...tags,
@@ -45,7 +56,7 @@ const methodKeys = [
         for (const [tag, methods] of methodMap.entries()){
             const list = map.get(tag) ?? [];
             list.push({
-                ...value,
+                ...pathItem,
                 path,
                 methods
             });

package/dist/server/index.js

@@ -134,7 +134,7 @@ function generateBody(method, schema) {
     });
 }
 
-function getSampleRequest$2(endpoint) {
+function getSampleRequest$3(endpoint) {
     const s = [];
     s.push(`curl -X ${endpoint.method} "${endpoint.url}"`);
     for (const param of endpoint.parameters){
@@ -161,7 +161,7 @@ function getSampleRequest$2(endpoint) {
     return s.flatMap((v, i)=>v.split('\n').map((line)=>i > 0 ? `  ${line}` : line).join('\n')).join(' \\\n');
 }
 
-function getSampleRequest$1(endpoint) {
+function getSampleRequest$2(endpoint) {
     const s = [];
     const options = new Map();
     const headers = new Map();
@@ -192,7 +192,7 @@ function getSampleRequest$1(endpoint) {
     return s.join('\n\n');
 }
 
-function getSampleRequest(endpoint) {
+function getSampleRequest$1(endpoint) {
     const imports = [
         'fmt',
         'net/http',
@@ -244,6 +244,32 @@ ${Array.from(variables.entries()).map(([k, v])=>`  ${k} := ${v}`).join('\n')}
 }`;
 }
 
+function getSampleRequest(endpoint) {
+    const headers = new Map();
+    const cookies = new Map();
+    const variables = new Map();
+    for (const param of endpoint.parameters){
+        if (param.in === 'header') headers.set(param.name, param.sample);
+        if (param.in === 'cookie') cookies.set(param.name, param.sample);
+    }
+    if (headers.size > 0) {
+        variables.set('headers', JSON.stringify(Object.fromEntries(headers.entries()), null, 2));
+    }
+    if (cookies.size > 0) {
+        variables.set('cookies', JSON.stringify(Object.fromEntries(cookies.entries()), null, 2));
+    }
+    if (endpoint.body) {
+        variables.set(endpoint.body.mediaType === 'multipart/form-data' ? 'data' : 'json', JSON.stringify(endpoint.body.sample, null, 2));
+    }
+    return `import requests
+
+url = ${JSON.stringify(endpoint.url)}
+${Array.from(variables.entries()).map(([k, v])=>`${k} = ${v}`).join('\n')}
+response = requests.request("${endpoint.method}", url${variables.size > 0 ? `, ${Array.from(variables.keys()).map((k)=>`${k}=${k}`).join(', ')}` : ''})
+
+print(response.text)`;
+}
+
 async function getTypescriptSchema(endpoint, code) {
     if (code in endpoint.responses) {
         return compile(endpoint.responses[code].schema, 'Response', {
@@ -443,7 +469,6 @@ function heading(depth, child, ctx) {
 }
 
 const keys = {
-    example: 'Example',
     default: 'Default',
     minimum: 'Minimum',
     maximum: 'Maximum',
@@ -461,17 +486,6 @@ function Schema({ name, schema, ctx }) {
     const stack = ctx.stack ?? [];
     const { renderer } = ctx.render;
     const child = [];
-    function field(key, value) {
-        child.push(/*#__PURE__*/ jsxs("span", {
-            children: [
-                key,
-                ": ",
-                /*#__PURE__*/ jsx("code", {
-                    children: value
-                })
-            ]
-        }, key));
-    }
     // object type
     if (isObject(schema) && parseObject) {
         const { additionalProperties, properties } = schema;
@@ -510,15 +524,32 @@ function Schema({ name, schema, ctx }) {
     if (schema.description) child.push(/*#__PURE__*/ jsx(Markdown, {
         text: schema.description
     }, "description"));
+    const fields = [];
     for (const [key, value] of Object.entries(keys)){
         if (key in schema) {
-            field(value, JSON.stringify(schema[key]));
+            fields.push({
+                key: value,
+                value: JSON.stringify(schema[key])
+            });
         }
     }
-    // enum types
     if (schema.enum) {
-        field('Value in', schema.enum.map((value)=>JSON.stringify(value)).join(' | '));
+        fields.push({
+            key: 'Value in',
+            value: schema.enum.map((value)=>JSON.stringify(value)).join(' | ')
+        });
     }
+    if (fields.length > 0) child.push(/*#__PURE__*/ jsx("p", {
+        children: fields.map((field)=>/*#__PURE__*/ jsxs("span", {
+                children: [
+                    field.key,
+                    ": ",
+                    /*#__PURE__*/ jsx("code", {
+                        children: field.value
+                    })
+                ]
+            }, field.key))
+    }, "fields"));
     if (isObject(schema) && !parseObject) {
         child.push(/*#__PURE__*/ jsx(renderer.ObjectCollapsible, {
             name: "Attributes",
@@ -537,7 +568,7 @@ function Schema({ name, schema, ctx }) {
             name: name,
             children: /*#__PURE__*/ jsx(Schema, {
                 name: name,
-                schema: combineSchema(schema.allOf.map(noRef)),
+                schema: combineSchema(noRef(schema.allOf)),
                 ctx: {
                     ...ctx,
                     parseObject: true,
@@ -578,6 +609,7 @@ function Schema({ name, schema, ctx }) {
     return /*#__PURE__*/ jsx(renderer.Property, {
         name: name,
         type: getSchemaType(schema, ctx),
+        required: ctx.required,
         deprecated: schema.deprecated,
         children: child
     });
@@ -601,7 +633,7 @@ function Schema({ name, schema, ctx }) {
             Object.assign(result.additionalProperties, s.additionalProperties);
         }
         if (s.allOf) {
-            add(combineSchema(s.allOf.map(noRef)));
+            add(combineSchema(noRef(s.allOf)));
         }
     }
     schema.forEach(add);
@@ -750,19 +782,24 @@ async function APIExample({ method, endpoint, ctx }) {
     const samples = dedupe([
         {
             label: 'cURL',
-            source: getSampleRequest$2(endpoint),
+            source: getSampleRequest$3(endpoint),
             lang: 'bash'
         },
         {
             label: 'JavaScript',
-            source: getSampleRequest$1(endpoint),
+            source: getSampleRequest$2(endpoint),
             lang: 'js'
         },
         {
             label: 'Go',
-            source: getSampleRequest(endpoint),
+            source: getSampleRequest$1(endpoint),
             lang: 'go'
         },
+        {
+            label: 'Python',
+            source: getSampleRequest(endpoint),
+            lang: 'python'
+        },
         ...ctx.generateCodeSamples ? await ctx.generateCodeSamples(endpoint) : [],
         ...method['x-codeSamples'] ?? []
     ]).filter((item)=>item.source !== undefined);
@@ -931,14 +968,36 @@ async function ResponseTabs({ endpoint, operation, ctx: { renderer, generateType
     });
 }
 
-function createMethod(method, operation) {
+/**
+ * Summarize method endpoint information
+ */ function createMethod(method, path, operation) {
     return {
+        description: path.description,
+        summary: path.summary,
         ...operation,
-        parameters: operation.parameters ?? [],
+        parameters: [
+            ...noRef(operation.parameters ?? []),
+            ...noRef(path.parameters ?? [])
+        ],
         method: method.toUpperCase()
     };
 }
 
+const sharedTransformers = [
+    {
+        name: 'fumadocs:pre-process',
+        line (hast) {
+            if (hast.children.length === 0) {
+                // Keep the empty lines when using grid layout
+                hast.children.push({
+                    type: 'text',
+                    value: ' '
+                });
+            }
+        }
+    }
+];
+
 const highlighter = await createHighlighter({
     themes: Object.values(bundledThemes),
     langs: Object.values(bundledLanguages)
@@ -951,7 +1010,8 @@ function CodeBlock({ code, lang, ...props }) {
             themes: {
                 light: 'github-light',
                 dark: 'github-dark'
-            }
+            },
+            transformers: sharedTransformers
         });
     }, [
         code,
@@ -1016,9 +1076,11 @@ async function APIPage(props) {
     return /*#__PURE__*/ jsx(ctx.renderer.Root, {
         baseUrl: ctx.baseUrl,
         children: operations.map((item)=>{
-            const operation = document.paths[item.path]?.[item.method];
+            const pathItem = document.paths[item.path];
+            if (!pathItem) return null;
+            const operation = pathItem[item.method];
             if (!operation) return null;
-            const method = createMethod(item.method, operation);
+            const method = createMethod(item.method, pathItem, operation);
             return /*#__PURE__*/ jsx(Operation, {
                 method: method,
                 path: item.path,

package/dist/ui/{client-client-34yX5eij.js → client-client-CgPBB3ii.js}

@@ -64,7 +64,7 @@ function useSchemaContext() {
     return ctx;
 }
 
-const APIPlayground = dynamic(()=>import('./playground-client-itvkUjgt.js').then((mod)=>mod.APIPlayground));
+const APIPlayground = dynamic(()=>import('./playground-client-CthJtmMz.js').then((mod)=>mod.APIPlayground));
 function Root({ children, baseUrl, className, ...props }) {
     return /*#__PURE__*/ jsx("div", {
         className: cn('flex flex-col gap-24 text-sm text-fd-muted-foreground', className),

package/dist/ui/index.js

@@ -3,8 +3,8 @@ import { cn } from 'fumadocs-ui/components/api';
 import { Fragment } from 'react';
 import { Accordions, Accordion } from 'fumadocs-ui/components/accordion';
 import { cva } from 'class-variance-authority';
-import { C as CopyRouteButton } from './client-client-34yX5eij.js';
-export { A as APIPlayground, R as Root, u as useSchemaContext } from './client-client-34yX5eij.js';
+import { C as CopyRouteButton } from './client-client-CgPBB3ii.js';
+export { A as APIPlayground, R as Root, u as useSchemaContext } from './client-client-CgPBB3ii.js';
 
 const badgeVariants = cva('rounded border px-1.5 py-1 text-xs font-medium leading-[12px]', {
     variants: {

package/dist/ui/{playground-client-itvkUjgt.js → playground-client-CthJtmMz.js}

@@ -6,7 +6,7 @@ import { FormProvider, Controller, useFormContext, useFieldArray, useForm, useWa
 import useSWRImmutable from 'swr/immutable';
 import { Accordions, Accordion } from 'fumadocs-ui/components/accordion';
 import { cn, buttonVariants } from 'fumadocs-ui/components/api';
-import { u as useSchemaContext, a as useApiContext, S as SchemaContext } from './client-client-34yX5eij.js';
+import { u as useSchemaContext, a as useApiContext, S as SchemaContext } from './client-client-CgPBB3ii.js';
 import { Slot } from '@radix-ui/react-slot';
 import { cva } from 'class-variance-authority';
 import { CircleCheckIcon, CircleXIcon, ChevronDown, ChevronUp, Check, Trash2, Plus } from 'lucide-react';
@@ -809,6 +809,21 @@ function ArrayInput({ fieldName, field, ...props }) {
     });
 }
 
+const sharedTransformers = [
+    {
+        name: 'fumadocs:pre-process',
+        line (hast) {
+            if (hast.children.length === 0) {
+                // Keep the empty lines when using grid layout
+                hast.children.push({
+                    type: 'text',
+                    value: ' '
+                });
+            }
+        }
+    }
+];
+
 function CodeBlock({ code, lang = 'json', ...props }) {
     const { highlighter } = useApiContext();
     const [html, setHtml] = useState('');
@@ -820,7 +835,8 @@ function CodeBlock({ code, lang = 'json', ...props }) {
             themes: {
                 light: 'github-light',
                 dark: 'github-dark'
-            }
+            },
+            transformers: sharedTransformers
         });
         setHtml(themedHtml);
     }, [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fumadocs-openapi",
-  "version": "5.2.1",
+  "version": "5.3.0",
   "description": "Generate MDX docs for your OpenAPI spec",
   "keywords": [
     "NextJs",
@@ -60,8 +60,8 @@
     "remark": "^15.0.0",
     "shiki": "^1.13.0",
     "swr": "^2.2.5",
-    "fumadocs-core": "13.3.0",
-    "fumadocs-ui": "13.3.0"
+    "fumadocs-core": "13.3.2",
+    "fumadocs-ui": "13.3.2"
   },
   "devDependencies": {
     "@types/js-yaml": "^4.0.9",