fumadocs-openapi 2.0.5 → 3.0.0

package/dist/index.d.ts

@@ -1,28 +1,66 @@
 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 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;
+    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`.
      */
-    componentsImportPath?: string;
-    render?: (title: string | undefined, description: string | undefined, content: string) => Partial<RenderResult>;
+    imports?: {
+        names: string[];
+        from: string;
+    }[];
+    /**
+     * Customise frontmatter
+     */
+    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 +81,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 +95,11 @@ interface MethodInformation extends OpenAPIV3.OperationObject {
     parameters: OpenAPIV3.ParameterObject[];
     method: string;
 }
+interface RenderContext {
+    renderer: Renderer;
+    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 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,42 +68,53 @@ 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)
+};
+
+// 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}
+---
+
+${finalImports}
+
+${Root(content)}`;
 }
 
 // src/samples/index.ts
@@ -75,7 +134,7 @@ function getValue(value) {
 }
 
 // src/samples/index.ts
-function createEndpoint(path, method, baseUrl = "https://example.com") {
+function createEndpoint(path, method, baseUrl) {
   const params = [];
   const responses = {};
   for (const param of method.parameters) {
@@ -184,22 +243,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 +298,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,7 +344,7 @@ function getSchemaType(schema) {
 }
 
 // src/render/operation.ts
-async function renderOperation(path, method, baseUrl) {
+async function renderOperation(path, method, ctx) {
   const info = [];
   const example = [];
   const title = method.summary ?? method.operationId;
@@ -301,12 +361,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 +384,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 = {
@@ -343,11 +405,11 @@ async function renderOperation(path, method, baseUrl) {
   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)
-  );
+  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 getResponseTable(operation) {
   const table = [];
@@ -358,131 +420,85 @@ 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 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()
+    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 +506,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 +518,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.0.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",