fumadocs-openapi 2.0.5 → 3.1.0

package/dist/index.d.ts

@@ -1,28 +1,73 @@
 import { OpenAPIV3 } from 'openapi-types';
 
-declare function dereference(pathOrDocument: string | OpenAPIV3.Document): Promise<OpenAPIV3.Document>;
+interface ResponsesProps {
+    items: string[];
+}
+interface ResponseProps {
+    value: string;
+}
+interface APIInfoProps {
+    method: string;
+    route: string;
+}
+interface PropertyProps {
+    name: string;
+    type: string;
+    required?: boolean;
+    deprecated?: boolean;
+}
+interface ObjectCollapsibleProps {
+    name: string;
+}
+interface RequestProps {
+    language: string;
+    name: string;
+    code: string;
+}
+interface Renderer {
+    Root: (child: string[]) => string;
+    API: (child: string[]) => string;
+    APIInfo: (props: APIInfoProps, child: string[]) => string;
+    APIExample: (child: string[]) => string;
+    Responses: (props: ResponsesProps, child: string[]) => string;
+    Response: (props: ResponseProps, child: string[]) => string;
+    Requests: (items: string[], child: string[]) => string;
+    Request: (props: RequestProps) => string;
+    ResponseTypes: (child: string[]) => string;
+    ExampleResponse: (json: string) => string;
+    TypeScriptResponse: (code: string) => string;
+    /**
+     * Collapsible to show object schemas
+     */
+    ObjectCollapsible: (props: ObjectCollapsibleProps, child: string[]) => string;
+    Property: (props: PropertyProps, child: string[]) => string;
+}
+declare const defaultRenderer: Renderer;
+
 interface GenerateOptions {
-    tag?: string;
     /**
-     * The import path of your API components, it must exports all components in `fumadocs-ui/components/api`
+     * The imports of your MDX components.
      *
-     * @defaultValue `fumadocs-ui/components/api`
+     * If not specified, import required components from `fumadocs-ui/components/api`.
+     */
+    imports?: {
+        names: string[];
+        from: string;
+    }[];
+    /**
+     * Customise frontmatter
      */
-    componentsImportPath?: string;
-    render?: (title: string | undefined, description: string | undefined, content: string) => Partial<RenderResult>;
+    frontmatter?: (title: string, description: string | undefined) => Record<string, unknown>;
+    renderer?: Partial<Renderer>;
 }
-interface RenderResult {
-    frontmatter: string;
-    imports: string[];
+interface GenerateTagOutput {
+    tag: string;
     content: string;
 }
 declare function generate(pathOrDocument: string | OpenAPIV3.Document, options?: GenerateOptions): Promise<string>;
-declare function generateTags(pathOrDocument: string | OpenAPIV3.Document, options?: Omit<GenerateOptions, 'tag'>): Promise<{
-    tag: string;
-    content: string;
-}[]>;
+declare function generateTags(pathOrDocument: string | OpenAPIV3.Document, options?: GenerateOptions): Promise<GenerateTagOutput[]>;
 
-interface Config {
+interface Config extends GenerateOptions {
     /**
      * Schema files
      */
@@ -43,13 +88,9 @@ interface Config {
      * Specify name for output file
      */
     name?: (type: 'file' | 'tag', name: string) => string;
-    /**
-     * Modify output file
-     */
-    render?: NonNullable<GenerateOptions['render']>;
     cwd?: string;
 }
-declare function generateFiles({ input, output, name: nameFn, per, render, cwd, }: Config): Promise<void>;
+declare function generateFiles({ input, output, name: nameFn, per, cwd, ...options }: Config): Promise<void>;
 
 interface RouteInformation {
     path: string;
@@ -61,5 +102,12 @@ interface MethodInformation extends OpenAPIV3.OperationObject {
     parameters: OpenAPIV3.ParameterObject[];
     method: string;
 }
+interface RenderContext {
+    renderer: Renderer;
+    document: OpenAPIV3.Document;
+    baseUrl: string;
+}
+
+declare function createElement(name: string, props: object, ...child: string[]): string;
 
-export { type Config, type GenerateOptions, type MethodInformation, type RouteInformation, dereference, generate, generateFiles, generateTags };
+export { type APIInfoProps, type Config, type GenerateOptions, type GenerateTagOutput, type MethodInformation, type ObjectCollapsibleProps, type PropertyProps, type RenderContext, type Renderer, type RequestProps, type ResponseProps, type ResponsesProps, type RouteInformation, createElement, defaultRenderer, generate, generateFiles, generateTags };

package/dist/index.js

@@ -1,12 +1,60 @@
 // src/generate.ts
 import Parser from "@apidevtools/json-schema-ref-parser";
 
+// src/build-routes.ts
+var methodKeys = [
+  "get",
+  "post",
+  "patch",
+  "delete",
+  "head",
+  "put"
+];
+function buildRoutes(document) {
+  const map = /* @__PURE__ */ new Map();
+  for (const [path, value] of Object.entries(document.paths)) {
+    if (!value) continue;
+    const methodMap = /* @__PURE__ */ new Map();
+    for (const methodKey of methodKeys) {
+      const operation = value[methodKey];
+      if (!operation) continue;
+      const info = buildOperation(methodKey, 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({
+        ...value,
+        path,
+        methods
+      });
+      map.set(tag, list);
+    }
+  }
+  return map;
+}
+function buildOperation(method, operation) {
+  return {
+    ...operation,
+    parameters: operation.parameters ?? [],
+    method: method.toUpperCase()
+  };
+}
+
+// src/render/page.ts
+import { dump } from "js-yaml";
+
 // src/render/element.ts
 function createElement(name, props, ...child) {
   const s = [];
   const params = Object.entries(props).map(([key, value]) => `${key}={${JSON.stringify(value)}}`).join(" ");
   s.push(params.length > 0 ? `<${name} ${params}>` : `<${name}>`);
-  s.push(...child);
+  s.push(...child.filter((v) => v.length > 0));
   s.push(`</${name}>`);
   return s.join("\n\n");
 }
@@ -20,48 +68,58 @@ function span(child) {
 function codeblock({ language, title }, child) {
   return [
     title ? `\`\`\`${language} title=${JSON.stringify(title)}` : `\`\`\`${language}`,
-    child,
+    child.trim(),
     "```"
   ].join("\n");
 }
 
-// src/render/custom.ts
-function api(...child) {
-  return createElement("API", {}, ...child);
-}
-function apiExample(...child) {
-  return createElement("APIExample", {}, ...child);
-}
-function root(...child) {
-  return createElement("Root", {}, ...child);
-}
-function apiInfo(props, ...child) {
-  return createElement("APIInfo", props, ...child);
-}
-function accordions(...child) {
-  return createElement("Accordions", {}, ...child);
-}
-function accordion(props, ...child) {
-  return createElement("Accordion", props, ...child);
-}
-function tabs(props, ...child) {
-  return createElement("Tabs", props, ...child);
-}
-function tab(props, ...child) {
-  return createElement("Tab", props, ...child);
-}
-function property({ required = false, deprecated = false, ...props }, ...child) {
-  return createElement(
-    "Property",
-    { required, deprecated, ...props },
-    ...child
-  );
-}
+// src/render/renderer.ts
+var defaultRenderer = {
+  Root: (child) => createElement("Root", {}, ...child),
+  API: (child) => createElement("API", {}, ...child),
+  APIInfo: (props, child) => createElement("APIInfo", props, ...child),
+  APIExample: (child) => createElement("APIExample", {}, ...child),
+  Responses: (props, child) => createElement("Responses", props, ...child),
+  Response: (props, child) => createElement("Response", props, ...child),
+  ResponseTypes: (child) => createElement("ResponseTypes", {}, ...child),
+  ExampleResponse: (json) => createElement("ExampleResponse", {}, codeblock({ language: "json" }, json)),
+  TypeScriptResponse: (code) => createElement(
+    "TypeScriptResponse",
+    {},
+    codeblock({ language: "ts" }, code)
+  ),
+  Property: (props, child) => createElement("Property", props, ...child),
+  ObjectCollapsible: (props, child) => createElement("ObjectCollapsible", props, ...child),
+  Requests: (items, child) => createElement("Requests", { items }, ...child),
+  Request: ({ language, code, name }) => createElement("Request", { value: name }, codeblock({ language }, code))
+};
 
-// src/samples/index.ts
-import { sample } from "openapi-sampler";
+// src/render/page.ts
+function renderPage(title, description, content, options) {
+  const banner = dump({
+    title,
+    description,
+    ...options.frontmatter?.(title, description)
+  }).trim();
+  const finalImports = (options.imports ?? [
+    {
+      names: Object.keys(defaultRenderer),
+      from: "fumadocs-ui/components/api"
+    }
+  ]).map(
+    (item) => `import { ${item.names.join(", ")} } from ${JSON.stringify(item.from)};`
+  ).join("\n");
+  const Root = options.renderer?.Root ?? defaultRenderer.Root;
+  return `---
+${banner}
+---
 
-// src/utils.ts
+${finalImports}
+
+${Root(content)}`;
+}
+
+// src/utils/schema.ts
 function noRef(v) {
   return v;
 }
@@ -70,12 +128,21 @@ function getPreferredMedia(body) {
   if ("application/json" in body) return body["application/json"];
   return Object.values(body)[0];
 }
-function getValue(value) {
+function toSampleInput(value) {
   return typeof value === "string" ? value : JSON.stringify(value, null, 2);
 }
 
-// src/samples/index.ts
-function createEndpoint(path, method, baseUrl = "https://example.com") {
+// src/utils/generate-input.ts
+import { sample } from "openapi-sampler";
+function generateInput(method, schema) {
+  return sample(schema, {
+    skipReadOnly: method !== "GET",
+    skipWriteOnly: method === "GET"
+  });
+}
+
+// src/endpoint.ts
+function createEndpoint(path, method, baseUrl) {
   const params = [];
   const responses = {};
   for (const param of method.parameters) {
@@ -102,33 +169,28 @@ function createEndpoint(path, method, baseUrl = "https://example.com") {
   let pathWithParameters = path;
   const queryParams = new URLSearchParams();
   for (const param of params) {
-    const value = generateSample(method.method, param.schema);
-    if (param.in === "query") queryParams.append(param.name, getValue(value));
+    const value = generateInput(method.method, param.schema);
+    if (param.in === "query")
+      queryParams.append(param.name, toSampleInput(value));
     if (param.in === "path")
       pathWithParameters = pathWithParameters.replace(
         `{${param.name}}`,
-        getValue(value)
+        toSampleInput(value)
       );
   }
   return {
     url: new URL(pathWithParameters, baseUrl).toString(),
-    body: bodySchema ? generateSample(method.method, bodySchema) : void 0,
+    body: bodySchema ? generateInput(method.method, bodySchema) : void 0,
     responses,
     method: method.method,
     parameters: params
   };
 }
-function generateSample(method, schema) {
-  return sample(schema, {
-    skipReadOnly: method !== "GET",
-    skipWriteOnly: method === "GET"
-  });
-}
 
-// src/samples/response.ts
+// src/utils/generate-response.ts
 function getExampleResponse(endpoint, code) {
   if (code in endpoint.responses) {
-    const value = generateSample(
+    const value = generateInput(
       endpoint.method,
       endpoint.responses[code].schema
     );
@@ -136,38 +198,66 @@ function getExampleResponse(endpoint, code) {
   }
 }
 
-// src/samples/typescript.ts
-import { compile } from "json-schema-to-typescript";
-async function getTypescript(endpoint, code) {
-  if (code in endpoint.responses) {
-    return compile(endpoint.responses[code].schema, "Response", {
-      bannerComment: "",
-      additionalProperties: false,
-      format: true,
-      enableConstEnums: false
-    });
-  }
-}
-
-// src/samples/curl.ts
+// src/requests/curl.ts
 function getSampleRequest(endpoint) {
   const s = [];
   s.push(`curl -X ${endpoint.method} "${endpoint.url}"`);
   for (const param of endpoint.parameters) {
     if (param.in === "header") {
-      const value = generateSample(endpoint.method, param.schema);
-      const header = `${param.name}: ${getValue2(value)}`;
+      const value = generateInput(endpoint.method, param.schema);
+      const header = `${param.name}: ${toSampleInput(value)}`;
       s.push(`-H "${header}"`);
     }
     if (param.in === "formData") {
       console.log("Request example for form data is not supported");
     }
   }
-  if (endpoint.body) s.push(`-d '${getValue2(endpoint.body)}'`);
+  if (endpoint.body) s.push(`-d '${toSampleInput(endpoint.body)}'`);
   return s.join(" \\\n  ");
 }
-function getValue2(value) {
-  return typeof value === "string" ? value : JSON.stringify(value, null, 2);
+
+// src/requests/javascript.ts
+function getSampleRequest2(endpoint) {
+  const s = [];
+  const options = /* @__PURE__ */ new Map();
+  const headers = {};
+  const formData = {};
+  for (const param of endpoint.parameters) {
+    if (param.in === "header") {
+      headers[param.name] = generateInput(endpoint.method, param.schema);
+    }
+    if (param.in === "formData") {
+      formData[param.name] = generateInput(endpoint.method, param.schema);
+    }
+  }
+  options.set("method", JSON.stringify(endpoint.method));
+  if (Object.keys(headers).length > 0) {
+    options.set("headers", JSON.stringify(headers, void 0, 2));
+  }
+  if (Object.keys(formData).length > 0) {
+    s.push(`const formData = new FormData();`);
+    for (const [key, value] of Object.entries(formData))
+      s.push(`formData.set(${key}, ${JSON.stringify(value)}`);
+    options.set("body", "formData");
+  }
+  const optionsStr = Array.from(options.entries()).map(([k, v]) => `  ${k}: ${v}`).join(",\n");
+  s.push(`fetch(${JSON.stringify(endpoint.url)}, {
+${optionsStr}
+});`);
+  return s.join("\n\n");
+}
+
+// src/utils/get-typescript-schema.ts
+import { compile } from "json-schema-to-typescript";
+async function getTypescriptSchema(endpoint, code) {
+  if (code in endpoint.responses) {
+    return compile(endpoint.responses[code].schema, "Response", {
+      bannerComment: "",
+      additionalProperties: false,
+      format: true,
+      enableConstEnums: false
+    });
+  }
 }
 
 // src/render/schema.ts
@@ -184,22 +274,26 @@ var keys = {
 function isObject(schema) {
   return schema.type === "object" || schema.properties !== void 0;
 }
-function schemaElement(name, schema, { parseObject, ...ctx }) {
+function schemaElement(name, schema, ctx) {
   if (schema.readOnly && !ctx.readOnly) return "";
   if (schema.writeOnly && !ctx.writeOnly) return "";
+  const { renderer } = ctx.render;
   const child = [];
   function field(key, value) {
     child.push(span(`${key}:  \`${value}\``));
   }
-  if (isObject(schema) && parseObject) {
+  if (isObject(schema) && ctx.parseObject) {
     const { additionalProperties, properties } = schema;
     if (additionalProperties) {
       if (additionalProperties === true) {
         child.push(
-          property({
-            name: "[key: string]",
-            type: "any"
-          })
+          renderer.Property(
+            {
+              name: "[key: string]",
+              type: "any"
+            },
+            []
+          )
         );
       } else {
         child.push(
@@ -235,28 +329,25 @@ function schemaElement(name, schema, { parseObject, ...ctx }) {
     );
   }
   const resolved = resolveObjectType(schema);
-  if (resolved && !parseObject) {
+  if (resolved && !ctx.parseObject) {
     child.push(
-      accordions(
-        accordion(
-          { title: "Object Type" },
-          schemaElement(name, resolved, {
-            ...ctx,
-            parseObject: true,
-            required: false
-          })
-        )
-      )
+      renderer.ObjectCollapsible({ name }, [
+        schemaElement(name, resolved, {
+          ...ctx,
+          parseObject: true,
+          required: false
+        })
+      ])
     );
   }
-  return property(
+  return renderer.Property(
     {
       name,
       type: getSchemaType(schema),
       required: ctx.required,
       deprecated: schema.deprecated
     },
-    ...child
+    child
   );
 }
 function resolveObjectType(schema) {
@@ -284,13 +375,18 @@ function getSchemaType(schema) {
 }
 
 // src/render/operation.ts
-async function renderOperation(path, method, baseUrl) {
+async function renderOperation(path, method, ctx) {
+  const body = noRef(method.requestBody);
+  const security = method.security ?? ctx.document.security;
   const info = [];
   const example = [];
   const title = method.summary ?? method.operationId;
   if (title) info.push(`## ${title}`);
   if (method.description) info.push(p(method.description));
-  const body = noRef(method.requestBody);
+  if (security) {
+    info.push("### Authorization");
+    info.push(getAuthSection(security, ctx));
+  }
   if (body) {
     const bodySchema = getPreferredMedia(body.content)?.schema;
     if (!bodySchema) throw new Error();
@@ -301,12 +397,13 @@ async function renderOperation(path, method, baseUrl) {
         parseObject: true,
         readOnly: method.method === "GET",
         writeOnly: method.method !== "GET",
-        required: body.required ?? false
+        required: body.required ?? false,
+        render: ctx
       })
     );
   }
   const parameterGroups = /* @__PURE__ */ new Map();
-  const endpoint = createEndpoint(path, method, baseUrl);
+  const endpoint = createEndpoint(path, method, ctx.baseUrl);
   for (const param of method.parameters) {
     const schema = noRef(
       param.schema ?? getPreferredMedia(param.content ?? {})?.schema
@@ -323,7 +420,8 @@ async function renderOperation(path, method, baseUrl) {
         parseObject: false,
         readOnly: method.method === "GET",
         writeOnly: method.method !== "GET",
-        required: param.required ?? false
+        required: param.required ?? false,
+        render: ctx
       }
     );
     const groupName = {
@@ -341,13 +439,94 @@ async function renderOperation(path, method, baseUrl) {
   }
   info.push(getResponseTable(method));
   example.push(
-    codeblock({ language: "bash", title: "curl" }, getSampleRequest(endpoint))
-  );
-  example.push(await getResponseTabs(endpoint, method));
-  return api(
-    apiInfo({ method: method.method, route: path }, ...info),
-    apiExample(...example)
+    ctx.renderer.Requests(
+      ["cURL", "JavaScript"],
+      [
+        ctx.renderer.Request({
+          name: "cURL",
+          code: getSampleRequest(endpoint),
+          language: "bash"
+        }),
+        ctx.renderer.Request({
+          name: "JavaScript",
+          code: getSampleRequest2(endpoint),
+          language: "js"
+        })
+      ]
+    )
   );
+  example.push(await getResponseTabs(endpoint, method, ctx));
+  return ctx.renderer.API([
+    ctx.renderer.APIInfo({ method: method.method, route: path }, info),
+    ctx.renderer.APIExample(example)
+  ]);
+}
+function getAuthSection(requirements, { document, renderer }) {
+  const info = [];
+  const schemas = document.components?.securitySchemes ?? {};
+  for (const requirement of requirements) {
+    if (info.length > 0) info.push(`---`);
+    for (const [name, scopes] of Object.entries(requirement)) {
+      if (!(name in schemas)) continue;
+      const schema = noRef(schemas[name]);
+      if (schema.type === "http") {
+        info.push(
+          renderer.Property(
+            {
+              name: "Authorization",
+              type: {
+                basic: "Basic <token>",
+                bearer: "Bearer <token>"
+              }[schema.scheme] ?? "<token>",
+              required: true
+            },
+            [p(schema.description), `In: \`header\``]
+          )
+        );
+      }
+      if (schema.type === "oauth2") {
+        info.push(
+          renderer.Property(
+            {
+              name: "Authorization",
+              type: "Bearer <token>",
+              required: true
+            },
+            [
+              p(schema.description),
+              `In: \`header\``,
+              `Scope: \`${scopes.length > 0 ? scopes.join(", ") : "none"}\``
+            ]
+          )
+        );
+      }
+      if (schema.type === "apiKey") {
+        info.push(
+          renderer.Property(
+            {
+              name: schema.name,
+              type: "<token>",
+              required: true
+            },
+            [p(schema.description), `In: \`${schema.in}\``]
+          )
+        );
+      }
+      if (schema.type === "openIdConnect") {
+        info.push(
+          renderer.Property(
+            {
+              name: "OpenID Connect",
+              type: "<token>",
+              required: true
+            },
+            [p(schema.description)]
+          )
+        );
+      }
+    }
+  }
+  return info.join("\n\n");
 }
 function getResponseTable(operation) {
   const table = [];
@@ -358,131 +537,86 @@ function getResponseTable(operation) {
   });
   return table.join("\n");
 }
-async function getResponseTabs(endpoint, operation) {
+async function getResponseTabs(endpoint, operation, { renderer }) {
   const items = [];
   const child = [];
-  for (const [code, _] of Object.entries(operation.responses)) {
+  for (const code of Object.keys(operation.responses)) {
     const example = getExampleResponse(endpoint, code);
-    const ts = await getTypescript(endpoint, code);
+    const ts = await getTypescriptSchema(endpoint, code);
     const description = code in endpoint.responses ? endpoint.responses[code].schema.description : void 0;
     if (example && ts) {
       items.push(code);
       child.push(
-        tab(
-          { value: code },
+        renderer.Response({ value: code }, [
           p(description),
-          codeblock({ language: "json", title: "Example Response" }, example),
-          accordions(
-            accordion(
-              { title: "Typescript Definition" },
-              codeblock({ language: "ts" }, ts)
-            )
-          )
-        )
+          renderer.ResponseTypes([
+            renderer.ExampleResponse(example),
+            renderer.TypeScriptResponse(ts)
+          ])
+        ])
       );
     }
   }
   if (items.length === 0) return "";
-  return tabs(
+  return renderer.Responses(
     {
       items
     },
-    ...child
+    child
   );
 }
 
 // src/generate.ts
-async function dereference(pathOrDocument) {
-  return await Parser.dereference(pathOrDocument);
-}
 async function generate(pathOrDocument, options = {}) {
-  const document = await dereference(pathOrDocument);
-  const tag = options.tag ? document.tags?.find((item) => item.name === options.tag) : void 0;
-  const routes = Object.entries(document.paths).map(
-    ([key, value]) => {
-      if (!value) throw new Error("Invalid schema");
-      const methodKeys = [
-        "get",
-        "post",
-        "patch",
-        "delete",
-        "head",
-        "put"
-      ];
-      const methods = [];
-      for (const methodKey of methodKeys) {
-        const operation = value[methodKey];
-        if (!operation) continue;
-        if (tag && !operation.tags?.includes(tag.name)) continue;
-        methods.push(buildOperation(methodKey, operation));
-      }
-      return {
-        ...value,
-        path: key,
-        methods
-      };
-    }
-  );
-  const serverUrl = document.servers?.[0].url;
-  const s = [];
+  const document = await Parser.dereference(pathOrDocument);
+  const routes = buildRoutes(document).get("all") ?? [];
+  const ctx = getContext(document, options);
+  const child = [];
   for (const route of routes) {
     for (const method of route.methods) {
-      s.push(await renderOperation(route.path, method, serverUrl));
+      child.push(await renderOperation(route.path, method, ctx));
     }
   }
-  return render(
-    tag?.name ?? document.info.title,
-    tag?.description ?? document.info.description,
-    root(...s),
+  return renderPage(
+    document.info.title,
+    document.info.description,
+    child,
     options
   );
 }
 async function generateTags(pathOrDocument, options = {}) {
-  const document = await dereference(pathOrDocument);
-  const results = document.tags?.map(async (tag) => {
-    return {
-      tag: tag.name,
-      content: await generate(document, {
-        tag: tag.name,
-        ...options
-      })
-    };
-  });
-  return Promise.all(results ?? []);
-}
-function render(title, description, content, {
-  render: fn,
-  componentsImportPath = "fumadocs-ui/components/api"
-}) {
-  const result = fn?.(title, description, content) ?? {};
-  const rendered = {
-    frontmatter: result.frontmatter ?? [
-      "---",
-      title && `title: ${title}`,
-      description && `description: |
-  ${description.split("\n").join("\n  ")}
-`,
-      "---"
-    ].filter(Boolean).join("\n"),
-    imports: result.imports ?? [
-      `import { Root, API, APIInfo, APIExample, Property } from '${componentsImportPath}'`,
-      `import { Tabs, Tab } from 'fumadocs-ui/components/tabs'`,
-      `import { Accordion, Accordions } from 'fumadocs-ui/components/accordion';`
-    ],
-    content: result.content ?? content
-  };
-  return [rendered.frontmatter, rendered.imports.join("\n"), rendered.content].filter(Boolean).join("\n\n");
+  const document = await Parser.dereference(pathOrDocument);
+  const tags = Array.from(buildRoutes(document).entries());
+  const ctx = getContext(document, options);
+  return await Promise.all(
+    tags.filter(([tag]) => tag !== "all").map(async ([tag, routes]) => {
+      const info = document.tags?.find((t) => t.name === tag);
+      const child = [];
+      for (const route of routes) {
+        for (const method of route.methods) {
+          child.push(await renderOperation(route.path, method, ctx));
+        }
+      }
+      return {
+        tag,
+        content: renderPage(tag, info?.description, child, options)
+      };
+    })
+  );
 }
-function buildOperation(method, operation) {
+function getContext(document, options) {
   return {
-    ...operation,
-    parameters: operation.parameters ?? [],
-    method: method.toUpperCase()
+    document,
+    renderer: {
+      ...defaultRenderer,
+      ...options.renderer
+    },
+    baseUrl: document.servers?.[0].url ?? "https://example.com"
   };
 }
 
 // src/generate-file.ts
-import { mkdirSync, writeFileSync } from "node:fs";
+import { mkdir, writeFile } from "node:fs/promises";
 import { dirname, join, parse } from "node:path";
 import fg from "fast-glob";
 async function generateFiles({
@@ -490,13 +624,10 @@ async function generateFiles({
   output,
   name: nameFn,
   per = "file",
-  render: render2,
-  cwd = process.cwd()
+  cwd = process.cwd(),
+  ...options
 }) {
   const outputDir = join(cwd, output);
-  const options = {
-    render: render2
-  };
   const resolvedInputs = await fg.glob(input, { absolute: true, cwd });
   await Promise.all(
     resolvedInputs.map(async (path) => {
@@ -505,27 +636,28 @@ async function generateFiles({
       if (per === "file") {
         const outPath = join(outputDir, `${filename}.mdx`);
         const result = await generate(path, options);
-        write(outPath, result);
+        await write(outPath, result);
+        console.log(`Generated: ${outPath}`);
+        return;
+      }
+      const results = await generateTags(path, options);
+      for (const result of results) {
+        let tagName = result.tag;
+        tagName = nameFn?.("tag", tagName) ?? tagName.toLowerCase().replace(/\s+/g, "-");
+        const outPath = join(outputDir, filename, `${tagName}.mdx`);
+        await write(outPath, result.content);
         console.log(`Generated: ${outPath}`);
-      } else {
-        const results = await generateTags(path, options);
-        results.forEach((result) => {
-          let tagName = result.tag;
-          tagName = nameFn?.("tag", tagName) ?? tagName.toLowerCase().replace(/\s+/g, "-");
-          const outPath = join(outputDir, filename, `${tagName}.mdx`);
-          write(outPath, result.content);
-          console.log(`Generated: ${outPath}`);
-        });
       }
     })
   );
 }
-function write(path, content) {
-  mkdirSync(dirname(path), { recursive: true });
-  writeFileSync(path, content);
+async function write(path, content) {
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, content);
 }
 export {
-  dereference,
+  createElement,
+  defaultRenderer,
   generate,
   generateFiles,
   generateTags

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fumadocs-openapi",
-  "version": "2.0.5",
+  "version": "3.1.0",
   "description": "Generate MDX docs for your OpenAPI spec",
   "keywords": [
     "NextJs",
@@ -19,10 +19,12 @@
   "dependencies": {
     "@apidevtools/json-schema-ref-parser": "^11.6.4",
     "fast-glob": "^3.3.1",
+    "js-yaml": "^4.1.0",
     "json-schema-to-typescript": "^14.0.5",
     "openapi-sampler": "^1.5.1"
   },
   "devDependencies": {
+    "@types/js-yaml": "^4.0.9",
     "@types/node": "18.17.5",
     "@types/openapi-sampler": "^1.0.3",
     "openapi-types": "^12.1.3",