fumadocs-openapi 5.7.5 → 5.8.0

package/dist/server/index.js

@@ -1,6 +1,5 @@
-import { jsx, Fragment, jsxs } from 'react/jsx-runtime';
+import { jsx, jsxs, Fragment } from 'react/jsx-runtime';
 import Slugger from 'github-slugger';
-import Parser from '@apidevtools/json-schema-ref-parser';
 import { Fragment as Fragment$1 } from 'react';
 import { sample } from 'openapi-sampler';
 import { compile } from '@fumari/json-schema-to-typescript';
@@ -10,16 +9,15 @@ import { remark } from 'remark';
 import remarkRehype from 'remark-rehype';
 import { toJsxRuntime } from 'hast-util-to-jsx-runtime';
 import { Heading } from 'fumadocs-ui/components/heading';
-import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
-import { Accordion, Accordions } from 'fumadocs-ui/components/accordion';
+import { Tabs, Tab } from 'fumadocs-ui/components/tabs';
+import { Accordions, Accordion } from 'fumadocs-ui/components/accordion';
 import * as Base from 'fumadocs-ui/components/codeblock';
 import { highlight } from 'fumadocs-core/server';
-import { APIPlayground, ObjectCollapsible, Property, APIExample as APIExample$1, APIInfo, API, Root } from '../ui/index.js';
+import { Root, API, APIInfo, APIExample as APIExample$1, Property, ObjectCollapsible, APIPlayground } from '../ui/index.js';
+import Parser from '@apidevtools/json-schema-ref-parser';
+import { upgrade } from '@scalar/openapi-parser';
 import { cva } from 'class-variance-authority';
 
-function noRef(v) {
-    return v;
-}
 function getPreferredType(body) {
     if ('application/json' in body) return 'application/json';
     return Object.keys(body)[0];
@@ -29,13 +27,21 @@ function getPreferredType(body) {
  */ function toSampleInput(value) {
     return typeof value === 'string' ? value : JSON.stringify(value, null, 2);
 }
+function isNullable(schema, includeOneOf = true) {
+    if (Array.isArray(schema.type) && schema.type.includes('null')) return true;
+    if (includeOneOf && (schema.anyOf || schema.oneOf)) {
+        if (schema.anyOf?.some((item)=>isNullable(item))) return true;
+        if (schema.oneOf?.some((item)=>isNullable(item))) return true;
+    }
+    return false;
+}
 
 function getSecurities(requirement, document) {
     const results = [];
     const schemas = document.components?.securitySchemes ?? {};
     for (const [key, scopes] of Object.entries(requirement)){
         if (!(key in schemas)) return [];
-        const schema = noRef(schemas[key]);
+        const schema = schemas[key];
         results.push({
             ...schema,
             scopes
@@ -54,22 +60,22 @@ function getSecurityPrefix(security) {
 function generateSample(path, method, { baseUrl, document }) {
     const params = [];
     const responses = {};
-    for (const param of method.parameters){
+    for (const param of method.parameters ?? []){
         if (param.schema) {
             params.push({
                 name: param.name,
                 in: param.in,
-                schema: noRef(param.schema),
+                schema: param.schema,
                 sample: param.example ?? sample(param.schema)
             });
         } else if (param.content) {
             const key = getPreferredType(param.content);
             const content = key ? param.content[key] : undefined;
-            if (!key || !content?.schema) throw new Error(`Cannot find parameter schema for ${param.name} in ${path} ${method.method}`);
+            if (!key || !content) throw new Error(`Cannot find parameter schema for ${param.name} in ${path} ${method.method}`);
             params.push({
                 name: param.name,
                 in: param.in,
-                schema: noRef(content.schema),
+                schema: content.schema ?? {},
                 sample: content.example ?? param.example ?? sample(content.schema)
             });
         }
@@ -90,22 +96,22 @@ function generateSample(path, method, { baseUrl, document }) {
     }
     let bodyOutput;
     if (method.requestBody) {
-        const body = noRef(method.requestBody).content;
+        const body = method.requestBody.content;
         const type = getPreferredType(body);
-        const schema = type ? noRef(body[type].schema) : undefined;
-        if (!type || !schema) throw new Error(`Cannot find body schema for ${path} ${method.method}`);
+        if (!type) throw new Error(`Cannot find body schema for ${path} ${method.method}: missing media type`);
+        const schema = (type ? body[type].schema : undefined) ?? {};
         bodyOutput = {
             schema,
             mediaType: type,
             sample: body[type].example ?? generateBody(method.method, schema)
         };
     }
-    for (const [code, value] of Object.entries(method.responses)){
-        const content = noRef(value).content;
+    for (const [code, response] of Object.entries(method.responses ?? {})){
+        const content = response.content;
         if (!content) continue;
         const mediaType = getPreferredType(content);
         if (!mediaType) continue;
-        const responseSchema = noRef(content[mediaType].schema);
+        const responseSchema = content[mediaType].schema;
         if (!responseSchema) continue;
         responses[code] = {
             mediaType,
@@ -272,13 +278,15 @@ response = requests.request("${endpoint.method}", url${variables.size > 0 ? `, $
 print(response.text)`;
 }
 
-async function getTypescriptSchema(endpoint, code) {
+async function getTypescriptSchema(endpoint, code, dereferenceMap) {
     if (code in endpoint.responses) {
         return compile(// re-running on the same schema results in error
         // because it uses `defineProperty` to define internal references
         // we clone the schema to fix this problem
-        structuredClone(endpoint.responses[code].schema), 'Response', {
+        // @ts-expect-error any types
+        endpoint.responses[code].schema, 'Response', {
             $refOptions: false,
+            schemaToId: dereferenceMap,
             bannerComment: '',
             additionalProperties: false,
             format: true,
@@ -289,7 +297,7 @@ async function getTypescriptSchema(endpoint, code) {
 
 function Playground({ path, method, ctx }) {
     let currentId = 0;
-    const bodyContent = noRef(method.requestBody)?.content;
+    const bodyContent = method.requestBody?.content;
     const mediaType = bodyContent ? getPreferredType(bodyContent) : undefined;
     const context = {
         allowFile: mediaType === 'multipart/form-data',
@@ -297,17 +305,18 @@ function Playground({ path, method, ctx }) {
         nextId () {
             return String(currentId++);
         },
-        registered: new WeakMap()
+        registered: new WeakMap(),
+        render: ctx
     };
     const props = {
         authorization: getAuthorizationField(method, ctx),
         method: method.method,
         route: path,
         bodyType: mediaType === 'multipart/form-data' ? 'form-data' : 'json',
-        path: method.parameters.filter((v)=>v.in === 'path').map((v)=>parameterToField(v, context)),
-        query: method.parameters.filter((v)=>v.in === 'query').map((v)=>parameterToField(v, context)),
-        header: method.parameters.filter((v)=>v.in === 'header').map((v)=>parameterToField(v, context)),
-        body: bodyContent && mediaType && bodyContent[mediaType].schema ? toSchema(noRef(bodyContent[mediaType].schema), true, context) : undefined,
+        path: method.parameters?.filter((v)=>v.in === 'path').map((v)=>parameterToField(v, context)),
+        query: method.parameters?.filter((v)=>v.in === 'query').map((v)=>parameterToField(v, context)),
+        header: method.parameters?.filter((v)=>v.in === 'header').map((v)=>parameterToField(v, context)),
+        body: bodyContent && mediaType && bodyContent[mediaType].schema ? toSchema(bodyContent[mediaType].schema, true, context) : undefined,
         schemas: context.schema
     };
     return /*#__PURE__*/ jsx(ctx.renderer.APIPlayground, {
@@ -342,7 +351,7 @@ function getIdFromSchema(schema, required, ctx) {
 function parameterToField(v, ctx) {
     return {
         name: v.name,
-        ...toSchema(noRef(v.schema) ?? {
+        ...toSchema(v.schema ?? {
             type: 'string'
         }, v.required ?? false, ctx)
     };
@@ -360,19 +369,19 @@ function toSchema(schema, required, ctx) {
             type: 'array',
             description: schema.description ?? schema.title,
             isRequired: required,
-            items: getIdFromSchema(noRef(schema.items), false, ctx)
+            items: getIdFromSchema(schema.items, false, ctx)
         };
     }
     if (schema.type === 'object' || schema.properties !== undefined || schema.allOf !== undefined) {
         const properties = {};
         Object.entries(schema.properties ?? {}).forEach(([key, prop])=>{
-            properties[key] = toReference(noRef(prop), schema.required?.includes(key) ?? false, ctx);
+            properties[key] = toReference(prop, schema.required?.includes(key) ?? false, ctx);
         });
         schema.allOf?.forEach((c)=>{
-            const field = toSchema(noRef(c), true, ctx);
+            const field = toSchema(c, true, ctx);
             if (field.type === 'object') Object.assign(properties, field.properties);
         });
-        const additional = noRef(schema.additionalProperties);
+        const additional = schema.additionalProperties;
         let additionalProperties;
         if (additional && typeof additional === 'object') {
             if (!additional.type && !additional.anyOf && !additional.allOf && !additional.oneOf) {
@@ -397,8 +406,7 @@ function toSchema(schema, required, ctx) {
             return {
                 type: 'switcher',
                 description: schema.description ?? schema.title,
-                items: Object.fromEntries(combine.map((c, idx)=>{
-                    const item = noRef(c);
+                items: Object.fromEntries(combine.map((item, idx)=>{
                     return [
                         item.title ?? item.type ?? `Item ${idx.toString()}`,
                         toReference(item, true, ctx)
@@ -419,6 +427,30 @@ function toSchema(schema, required, ctx) {
             description: schema.description ?? schema.title
         };
     }
+    if (Array.isArray(schema.type)) {
+        const items = {};
+        for (const type of schema.type){
+            if (type === 'array') {
+                items[type] = {
+                    type,
+                    items: 'items' in schema && schema.items ? toSchema(schema.items, false, ctx) : toSchema({}, required, ctx),
+                    isRequired: required
+                };
+            } else if (type !== 'null' && type !== 'object') {
+                items[type] = {
+                    type: type === 'integer' ? 'number' : type,
+                    isRequired: required,
+                    defaultValue: schema.example ?? schema.default ?? ''
+                };
+            }
+        }
+        return {
+            type: 'switcher',
+            description: schema.description ?? schema.title,
+            items,
+            isRequired: required
+        };
+    }
     return {
         type: schema.type === 'integer' ? 'number' : schema.type,
         defaultValue: schema.example ?? '',
@@ -477,35 +509,45 @@ function heading(depth, child, ctx) {
     };
     function add(s) {
         if (s.type) {
-            result.type = result.type ? 'object' : s.type;
+            var _result;
+            (_result = result).type ?? (_result.type = []);
+            if (!Array.isArray(result.type)) {
+                result.type = [
+                    result.type
+                ];
+            }
+            for (const v of Array.isArray(s.type) ? s.type : [
+                s.type
+            ]){
+                if (!result.type.includes(v)) {
+                    result.type.push(v);
+                }
+            }
         }
         if (s.properties) {
-            var _result;
-            (_result = result).properties ?? (_result.properties = {});
+            var _result1;
+            (_result1 = result).properties ?? (_result1.properties = {});
             Object.assign(result.properties, s.properties);
         }
         if (s.additionalProperties === true) {
             result.additionalProperties = true;
         } else if (s.additionalProperties && typeof result.additionalProperties !== 'boolean') {
-            var _result1;
-            (_result1 = result).additionalProperties ?? (_result1.additionalProperties = {});
+            var _result2;
+            (_result2 = result).additionalProperties ?? (_result2.additionalProperties = {});
             Object.assign(result.additionalProperties, s.additionalProperties);
         }
         if (s.required) {
-            var _result2;
-            (_result2 = result).required ?? (_result2.required = []);
+            var _result3;
+            (_result3 = result).required ?? (_result3.required = []);
             result.required.push(...s.required);
         }
         if (s.enum && s.enum.length > 0) {
-            var _result3;
-            (_result3 = result).enum ?? (_result3.enum = []);
+            var _result4;
+            (_result4 = result).enum ?? (_result4.enum = []);
             result.enum.push(...s.enum);
         }
-        if (s.nullable) {
-            result.nullable = true;
-        }
         if (s.allOf) {
-            noRef(s.allOf).forEach(add);
+            s.allOf.forEach(add);
         }
     }
     schema.forEach(add);
@@ -541,7 +583,7 @@ function Schema({ name, schema, ctx }) {
         } else if (additionalProperties) {
             child.push(/*#__PURE__*/ jsx(Schema, {
                 name: "[key: string]",
-                schema: noRef(additionalProperties),
+                schema: additionalProperties,
                 ctx: {
                     ...ctx,
                     required: false,
@@ -553,7 +595,7 @@ function Schema({ name, schema, ctx }) {
             const rendered = Object.entries(properties).map(([key, value])=>{
                 return /*#__PURE__*/ jsx(Schema, {
                     name: key,
-                    schema: noRef(value),
+                    schema: value,
                     ctx: {
                         ...ctx,
                         required: schema.required?.includes(key) ?? false,
@@ -568,7 +610,7 @@ function Schema({ name, schema, ctx }) {
     if (schema.allOf && parseObject) {
         return /*#__PURE__*/ jsx(Schema, {
             name: name,
-            schema: combineSchema(noRef(schema.allOf)),
+            schema: combineSchema(schema.allOf),
             ctx: ctx
         });
     }
@@ -602,7 +644,7 @@ function Schema({ name, schema, ctx }) {
                 ]
             }, field.key))
     }, "fields"));
-    if ((isObject(schema) || schema.allOf) && !parseObject) {
+    if (isObject(schema) && !parseObject && !stack.includes(schema)) {
         child.push(/*#__PURE__*/ jsx(renderer.ObjectCollapsible, {
             name: "Attributes",
             children: /*#__PURE__*/ jsx(Schema, {
@@ -611,7 +653,11 @@ function Schema({ name, schema, ctx }) {
                 ctx: {
                     ...ctx,
                     parseObject: true,
-                    required: false
+                    required: false,
+                    stack: [
+                        schema,
+                        ...stack
+                    ]
                 }
             })
         }, "attributes"));
@@ -624,13 +670,13 @@ function Schema({ name, schema, ctx }) {
             ...schema.type === 'array' ? [
                 schema.items
             ] : []
-        ].map(noRef).filter((s)=>isComplexType(s) && !stack.includes(s));
+        ].filter((s)=>isComplexType(s) && !stack.includes(s));
         const renderedMentionedTypes = mentionedObjectTypes.map((s, idx)=>{
             return /*#__PURE__*/ jsx(renderer.ObjectCollapsible, {
                 name: s.title ?? `Object ${(idx + 1).toString()}`,
                 children: /*#__PURE__*/ jsx(Schema, {
                     name: "element",
-                    schema: noRef(s),
+                    schema: s,
                     ctx: {
                         ...ctx,
                         stack: [
@@ -659,70 +705,82 @@ function Schema({ name, schema, ctx }) {
     if (schema.anyOf ?? schema.oneOf ?? schema.allOf) return true;
     return isObject(schema) || schema.type === 'array';
 }
-function getSchemaType(schema, ctx) {
-    if (schema.nullable) {
-        const type = getSchemaType({
-            ...schema,
-            nullable: false
-        }, ctx);
+function getSchemaType(schema, ctx, isRoot = true) {
+    if (isNullable(schema) && isRoot) {
+        const type = getSchemaType(schema, ctx, false);
         // null if schema only contains `nullable`
         return type === 'unknown' ? 'null' : `${type} | null`;
     }
     if (schema.title) return schema.title;
-    if (schema.type === 'array') return `array<${getSchemaType(noRef(schema.items), ctx)}>`;
-    if (schema.oneOf) return schema.oneOf.map((one)=>getSchemaType(noRef(one), ctx)).join(' | ');
+    if (schema.type === 'array') return `array<${getSchemaType(schema.items, ctx)}>`;
+    if (schema.oneOf) return schema.oneOf.map((one)=>getSchemaType(one, ctx, false)).filter((v)=>v !== 'unknown').join(' | ');
     if (schema.allOf) {
-        const allTypeNames = schema.allOf.map((one)=>getSchemaType(noRef(one), ctx));
-        const hasNull = allTypeNames.includes('null');
-        const nonNullTypes = allTypeNames.filter((v)=>v !== 'null');
-        const nonNullTypeNames = nonNullTypes.join(' & ');
-        if (!hasNull) return nonNullTypeNames;
-        if (nonNullTypes.length === 0) return 'null';
-        else if (nonNullTypes.length === 1 || !hasNull) return `${nonNullTypeNames} | null`;
-        else return `(${nonNullTypeNames}) | null`;
+        return schema.allOf.map((one)=>getSchemaType(one, ctx, false)).filter((v)=>v !== 'unknown').join(' & ');
     }
-    if (schema.not) return `not ${getSchemaType(noRef(schema.not), ctx)}`;
+    if (schema.not) return `not ${getSchemaType(schema.not, ctx, false)}`;
     if (schema.anyOf) {
-        return `Any properties in ${schema.anyOf.map((one)=>getSchemaType(noRef(one), ctx)).join(', ')}`;
+        return `Any properties in ${schema.anyOf.map((one)=>getSchemaType(one, ctx, false)).filter((v)=>v !== 'unknown').join(', ')}`;
     }
     if (schema.type === 'string' && schema.format === 'binary' && ctx.allowFile) return 'file';
-    if (schema.type) return schema.type;
+    if (schema.type && Array.isArray(schema.type)) {
+        const nonNullTypes = schema.type.filter((v)=>v !== 'null');
+        if (nonNullTypes.length > 0) return nonNullTypes.join(' | ');
+    } else if (schema.type && schema.type !== 'null') {
+        return schema.type;
+    }
     if (isObject(schema)) return 'object';
     return 'unknown';
 }
 
-function Operation({ baseUrls, path, method, ctx, hasHead }) {
-    let level = 2;
-    const body = noRef(method.requestBody);
+/**
+ * Summarize method endpoint information
+ */ function createMethod(method, path, operation) {
+    return {
+        description: path.description,
+        summary: path.summary,
+        ...operation,
+        parameters: [
+            ...operation.parameters ?? [],
+            ...path.parameters ?? []
+        ],
+        method: method.toUpperCase()
+    };
+}
+
+const methodKeys = [
+    'get',
+    'post',
+    'patch',
+    'delete',
+    'head',
+    'put'
+];
+
+function Operation({ type = 'operation', path, method, ctx, hasHead, headingLevel = 2 }) {
+    const { baseUrls } = ctx;
+    const body = method.requestBody;
     const security = method.security ?? ctx.document.security;
-    const info = [];
+    let headNode = null;
+    let bodyNode = null;
+    let callbacksNode = null;
     if (hasHead) {
-        info.push(heading(level, method.summary ?? (method.operationId ? idToTitle(method.operationId) : path), ctx));
-        level++;
-        if (method.description) {
-            info.push(/*#__PURE__*/ jsx(Markdown, {
-                text: method.description
-            }, "description"));
-        }
-    }
-    info.push(/*#__PURE__*/ jsx(Playground, {
-        path: path,
-        method: method,
-        ctx: ctx
-    }, "playground"));
-    if (security) {
-        info.push(heading(level, 'Authorization', ctx));
-        info.push(/*#__PURE__*/ jsx(AuthSection, {
-            requirements: security,
-            ctx: ctx
-        }, "auth"));
+        const title = method.summary ?? (method.operationId ? idToTitle(method.operationId) : path);
+        headNode = /*#__PURE__*/ jsxs(Fragment, {
+            children: [
+                heading(headingLevel, title, ctx),
+                method.description ? /*#__PURE__*/ jsx(Markdown, {
+                    text: method.description
+                }, "description") : null
+            ]
+        });
+        headingLevel++;
     }
     if (body) {
         const type = getPreferredType(body.content);
         if (!type) throw new Error(`No supported media type for body content: ${path}`);
-        info.push(/*#__PURE__*/ jsxs(Fragment$1, {
+        bodyNode = /*#__PURE__*/ jsxs(Fragment, {
             children: [
-                heading(level, 'Request Body', ctx),
+                heading(headingLevel, 'Request Body', ctx),
                 /*#__PURE__*/ jsxs("div", {
                     className: "mb-8 flex flex-row items-center justify-between gap-2",
                     children: [
@@ -739,7 +797,7 @@ function Operation({ baseUrls, path, method, ctx, hasHead }) {
                 }) : null,
                 /*#__PURE__*/ jsx(Schema, {
                     name: "body",
-                    schema: noRef(body.content[type].schema ?? {}),
+                    schema: body.content[type].schema ?? {},
                     ctx: {
                         readOnly: method.method === 'GET',
                         writeOnly: method.method !== 'GET',
@@ -749,11 +807,11 @@ function Operation({ baseUrls, path, method, ctx, hasHead }) {
                     }
                 })
             ]
-        }, "body"));
+        });
     }
     const parameterGroups = new Map();
     const endpoint = generateSample(path, method, ctx);
-    for (const param of method.parameters){
+    for (const param of method.parameters ?? []){
         const pInfo = endpoint.parameters.find((item)=>item.name === param.name && item.in === param.in);
         if (!pInfo) continue;
         const schema = pInfo.schema;
@@ -781,24 +839,81 @@ function Operation({ baseUrls, path, method, ctx, hasHead }) {
         }, param.name));
         parameterGroups.set(groupName, group);
     }
-    for (const [group, parameters] of Array.from(parameterGroups.entries())){
-        info.push(heading(level, group, ctx), ...parameters);
+    if (method.callbacks) {
+        callbacksNode = /*#__PURE__*/ jsxs(Fragment, {
+            children: [
+                heading(headingLevel, 'Webhooks', ctx),
+                Object.entries(method.callbacks).map(([name, callback])=>{
+                    const nodes = Object.entries(callback).map(([path, pathItem])=>{
+                        const pathNodes = methodKeys.map((method)=>{
+                            const operation = pathItem[method];
+                            if (!operation) return null;
+                            return /*#__PURE__*/ jsx(Operation, {
+                                type: "webhook",
+                                hasHead: true,
+                                path: path,
+                                headingLevel: headingLevel + 1,
+                                method: createMethod(method, pathItem, operation),
+                                ctx: ctx
+                            }, method);
+                        });
+                        return /*#__PURE__*/ jsx(Fragment$1, {
+                            children: pathNodes
+                        }, path);
+                    });
+                    return /*#__PURE__*/ jsx(Fragment$1, {
+                        children: nodes
+                    }, name);
+                })
+            ]
+        });
     }
-    return /*#__PURE__*/ jsxs(ctx.renderer.API, {
+    const info = /*#__PURE__*/ jsxs(ctx.renderer.APIInfo, {
+        head: headNode,
+        method: method.method,
+        route: path,
+        baseUrls: type === 'operation' ? baseUrls : [],
         children: [
-            /*#__PURE__*/ jsx(ctx.renderer.APIInfo, {
-                method: method.method,
-                route: path,
-                baseUrls: baseUrls,
-                children: info
-            }),
-            /*#__PURE__*/ jsx(APIExample, {
+            type === 'operation' ? /*#__PURE__*/ jsx(Playground, {
+                path: path,
                 method: method,
-                endpoint: endpoint,
                 ctx: ctx
-            })
+            }) : null,
+            security ? /*#__PURE__*/ jsxs(Fragment, {
+                children: [
+                    heading(headingLevel, 'Authorization', ctx),
+                    /*#__PURE__*/ jsx(AuthSection, {
+                        requirements: security,
+                        ctx: ctx
+                    })
+                ]
+            }) : null,
+            bodyNode,
+            Array.from(parameterGroups.entries()).map(([group, params])=>{
+                return /*#__PURE__*/ jsxs(Fragment$1, {
+                    children: [
+                        heading(headingLevel, group, ctx),
+                        params
+                    ]
+                }, group);
+            }),
+            callbacksNode
         ]
     });
+    if (type === 'operation') {
+        return /*#__PURE__*/ jsxs(ctx.renderer.API, {
+            children: [
+                info,
+                /*#__PURE__*/ jsx(APIExample, {
+                    method: method,
+                    endpoint: endpoint,
+                    ctx: ctx
+                })
+            ]
+        });
+    } else {
+        return info;
+    }
 }
 const defaultSamples = [
     {
@@ -875,6 +990,14 @@ function AuthSection({ ctx: { document, renderer }, requirements }) {
     for (const requirement of requirements){
         for (const schema of getSecurities(requirement, document)){
             const prefix = getSecurityPrefix(schema);
+            const scopeElement = schema.scopes.length > 0 ? /*#__PURE__*/ jsxs("p", {
+                children: [
+                    "Scope: ",
+                    /*#__PURE__*/ jsx("code", {
+                        children: schema.scopes.join(', ')
+                    })
+                ]
+            }) : null;
             if (schema.type === 'http') {
                 info.push(/*#__PURE__*/ jsxs(renderer.Property, {
                     name: "Authorization",
@@ -889,7 +1012,8 @@ function AuthSection({ ctx: { document, renderer }, requirements }) {
                                 "In: ",
                                 /*#__PURE__*/ jsx("code", {
                                     children: "header"
-                                })
+                                }),
+                                scopeElement
                             ]
                         })
                     ]
@@ -912,14 +1036,7 @@ function AuthSection({ ctx: { document, renderer }, requirements }) {
                                 })
                             ]
                         }),
-                        schema.scopes.length > 0 ? /*#__PURE__*/ jsxs("p", {
-                            children: [
-                                "Scope: ",
-                                /*#__PURE__*/ jsx("code", {
-                                    children: schema.scopes.join(', ')
-                                })
-                            ]
-                        }) : null
+                        scopeElement
                     ]
                 }, id++));
             }
@@ -936,32 +1053,37 @@ function AuthSection({ ctx: { document, renderer }, requirements }) {
                                 "In: ",
                                 /*#__PURE__*/ jsx("code", {
                                     children: schema.in
-                                })
+                                }),
+                                scopeElement
                             ]
                         })
                     ]
                 }, id++));
             }
             if (schema.type === 'openIdConnect') {
-                info.push(/*#__PURE__*/ jsx(renderer.Property, {
+                info.push(/*#__PURE__*/ jsxs(renderer.Property, {
                     name: "OpenID Connect",
                     type: "<token>",
                     required: true,
-                    children: schema.description ? /*#__PURE__*/ jsx(Markdown, {
-                        text: schema.description
-                    }) : null
+                    children: [
+                        schema.description ? /*#__PURE__*/ jsx(Markdown, {
+                            text: schema.description
+                        }) : null,
+                        scopeElement
+                    ]
                 }, id++));
             }
         }
     }
     return info;
 }
-async function ResponseTabs({ endpoint, operation, ctx: { renderer, generateTypeScriptSchema } }) {
+async function ResponseTabs({ endpoint, operation, ctx: { renderer, generateTypeScriptSchema, dereferenceMap } }) {
     const items = [];
     const children = [];
+    if (!operation.responses) return null;
     for (const code of Object.keys(operation.responses)){
         const types = [];
-        let description = noRef(operation.responses[code]).description;
+        let description = operation.responses[code].description;
         if (!description && code in endpoint.responses) description = endpoint.responses[code].schema.description ?? '';
         if (code in endpoint.responses) {
             types.push({
@@ -974,7 +1096,7 @@ async function ResponseTabs({ endpoint, operation, ctx: { renderer, generateType
         if (generateTypeScriptSchema) {
             ts = await generateTypeScriptSchema(endpoint, code);
         } else if (generateTypeScriptSchema === undefined) {
-            ts = await getTypescriptSchema(endpoint, code);
+            ts = await getTypescriptSchema(endpoint, code, dereferenceMap);
         }
         if (ts) {
             types.push({
@@ -1005,21 +1127,6 @@ async function ResponseTabs({ endpoint, operation, ctx: { renderer, generateType
     });
 }
 
-/**
- * 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()
-    };
-}
-
 async function CodeBlock({ code, lang, options, ...rest }) {
     const rendered = await highlight(code, {
         lang,
@@ -1082,38 +1189,79 @@ function createRenders(shikiOptions) {
 }
 
 const cache = new Map();
-async function APIPage(props) {
-    const { operations, hasHead = true } = props;
-    let document;
-    if (typeof props.document === 'string' && !props.disableCache) {
-        const cached = cache.get(props.document);
-        document = cached ?? await Parser.dereference(props.document);
-        cache.set(props.document, document);
-    } else {
-        document = await Parser.dereference(props.document);
+/**
+ * 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);
     }
-    const ctx = getContext(document, props);
-    return /*#__PURE__*/ jsx(ctx.renderer.Root, {
+    return processed;
+}
+
+async function APIPage(props) {
+    const { operations, hasHead = true, webhooks, disableCache = process.env.NODE_ENV === 'development' } = props;
+    const processed = await processDocument(props.document, disableCache);
+    const ctx = await getContext(processed, props);
+    const { document } = processed;
+    return /*#__PURE__*/ jsxs(ctx.renderer.Root, {
         baseUrl: ctx.baseUrl,
-        children: operations.map((item)=>{
-            const pathItem = document.paths[item.path];
-            if (!pathItem) return null;
-            const operation = pathItem[item.method];
-            if (!operation) return null;
-            const method = createMethod(item.method, pathItem, operation);
-            return /*#__PURE__*/ jsx(Operation, {
-                method: method,
-                path: item.path,
-                ctx: ctx,
-                baseUrls: document.servers ? document.servers.map((s)=>s.url) : [],
-                hasHead: hasHead
-            }, `${item.path}:${item.method}`);
-        })
+        children: [
+            operations?.map((item)=>{
+                const pathItem = document.paths?.[item.path];
+                if (!pathItem) return null;
+                const operation = pathItem[item.method];
+                if (!operation) return null;
+                const method = createMethod(item.method, pathItem, operation);
+                return /*#__PURE__*/ jsx(Operation, {
+                    method: method,
+                    path: item.path,
+                    ctx: ctx,
+                    hasHead: hasHead
+                }, `${item.path}:${item.method}`);
+            }),
+            webhooks?.map((item)=>{
+                const webhook = document.webhooks?.[item.name];
+                if (!webhook) return;
+                const hook = webhook[item.method];
+                if (!hook) return;
+                const method = createMethod(item.method, webhook, hook);
+                return /*#__PURE__*/ jsx(Operation, {
+                    type: "webhook",
+                    method: method,
+                    ctx: {
+                        ...ctx,
+                        baseUrl: 'http://localhost:8080'
+                    },
+                    path: `/${item.name}`,
+                    hasHead: hasHead
+                }, `${item.name}:${item.method}`);
+            })
+        ]
     });
 }
-function getContext(document, options) {
+async function getContext({ document, dereferenceMap }, options = {}) {
     return {
-        document,
+        document: document,
+        dereferenceMap,
         renderer: {
             ...createRenders(options.shikiOptions),
             ...options.renderer
@@ -1122,6 +1270,7 @@ function getContext(document, options) {
         generateTypeScriptSchema: options.generateTypeScriptSchema,
         generateCodeSamples: options.generateCodeSamples,
         baseUrl: document.servers?.[0].url ?? 'https://example.com',
+        baseUrls: document.servers?.map((s)=>s.url) ?? [],
         slugger: new Slugger()
     };
 }