fumadocs-openapi 3.1.3 → 3.3.0

package/dist/index.d.ts

@@ -44,6 +44,48 @@ interface Renderer {
 }
 declare const defaultRenderer: Renderer;
 
+interface CodeSample {
+    lang: string;
+    label: string;
+    source: string;
+}
+
+interface RouteInformation {
+    path: string;
+    summary?: string;
+    description?: string;
+    methods: MethodInformation[];
+}
+interface MethodInformation extends OpenAPIV3.OperationObject {
+    parameters: OpenAPIV3.ParameterObject[];
+    method: string;
+}
+interface RenderContext {
+    renderer: Renderer;
+    document: OpenAPIV3.Document;
+    baseUrl: string;
+    generateCodeSamples?: (endpoint: Endpoint) => CodeSample[];
+}
+
+interface Endpoint {
+    /**
+     * URL, including path and query parameters
+     */
+    url: string;
+    method: string;
+    body?: unknown;
+    responses: Record<string, Response>;
+    parameters: Parameter[];
+}
+interface Response {
+    schema: OpenAPIV3.SchemaObject;
+}
+interface Parameter {
+    name: string;
+    in: string;
+    schema: OpenAPIV3.SchemaObject;
+}
+
 interface GenerateOptions {
     /**
      * The imports of your MDX components.
@@ -60,6 +102,10 @@ interface GenerateOptions {
      * A `full: true` property will be added by default.
      */
     frontmatter?: (title: string, description: string | undefined) => Record<string, unknown>;
+    /**
+     * Generate code samples for endpoint
+     */
+    generateCodeSamples?: (endpoint: Endpoint) => CodeSample[];
     renderer?: Partial<Renderer>;
 }
 interface GenerateTagOutput {
@@ -99,22 +145,6 @@ interface Config extends GenerateOptions {
 }
 declare function generateFiles({ input, output, name: nameFn, per, cwd, ...options }: Config): Promise<void>;
 
-interface RouteInformation {
-    path: string;
-    summary?: string;
-    description?: string;
-    methods: MethodInformation[];
-}
-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 APIInfoProps, type Config, type GenerateOperationOutput, 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, generateOperations, generateTags };

package/dist/index.js

@@ -281,39 +281,43 @@ function isObject(schema) {
   return schema.type === "object" || schema.properties !== void 0;
 }
 function schemaElement(name, schema, ctx) {
+  return render(name, schema, {
+    ...ctx,
+    stack: []
+  });
+}
+function render(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}\``));
+    child.push(span(`${key}: \`${value}\``));
   }
   if (isObject(schema) && ctx.parseObject) {
     const { additionalProperties, properties } = schema;
-    if (additionalProperties) {
-      if (additionalProperties === true) {
-        child.push(
-          renderer.Property(
-            {
-              name: "[key: string]",
-              type: "any"
-            },
-            []
-          )
-        );
-      } else {
-        child.push(
-          schemaElement("[key: string]", noRef(additionalProperties), {
-            ...ctx,
-            required: false,
-            parseObject: false
-          })
-        );
-      }
+    if (additionalProperties === true) {
+      child.push(
+        renderer.Property(
+          {
+            name: "[key: string]",
+            type: "any"
+          },
+          []
+        )
+      );
+    } else if (additionalProperties) {
+      child.push(
+        render("[key: string]", noRef(additionalProperties), {
+          ...ctx,
+          required: false,
+          parseObject: false
+        })
+      );
     }
     Object.entries(properties ?? {}).forEach(([key, value]) => {
       child.push(
-        schemaElement(key, noRef(value), {
+        render(key, noRef(value), {
           ...ctx,
           required: schema.required?.includes(key) ?? false,
           parseObject: false
@@ -334,17 +338,38 @@ function schemaElement(name, schema, ctx) {
       schema.enum.map((value) => JSON.stringify(value)).join(" | ")
     );
   }
-  const resolved = resolveObjectType(schema);
-  if (resolved && !ctx.parseObject) {
+  if (isObject(schema) && !ctx.parseObject) {
     child.push(
       renderer.ObjectCollapsible({ name }, [
-        schemaElement(name, resolved, {
+        render(name, schema, {
           ...ctx,
           parseObject: true,
           required: false
         })
       ])
     );
+  } else {
+    const mentionedObjectTypes = [
+      ...schema.anyOf ?? schema.oneOf ?? schema.allOf ?? [],
+      ...schema.not ? [schema.not] : [],
+      ...schema.type === "array" ? [schema.items] : []
+    ].map(noRef).filter((s) => isComplexType(s) && !ctx.stack.includes(s));
+    ctx.stack.push(schema);
+    child.push(
+      ...mentionedObjectTypes.map(
+        (s, idx) => renderer.ObjectCollapsible(
+          { name: s.title ?? `Object ${(idx + 1).toString()}` },
+          [
+            render("element", noRef(s), {
+              ...ctx,
+              parseObject: true,
+              required: false
+            })
+          ]
+        )
+      )
+    );
+    ctx.stack.pop();
   }
   return renderer.Property(
     {
@@ -356,28 +381,29 @@ function schemaElement(name, schema, ctx) {
     child
   );
 }
-function resolveObjectType(schema) {
-  if (isObject(schema)) return schema;
-  if (schema.type === "array") {
-    return resolveObjectType(noRef(schema.items));
-  }
+function isComplexType(schema) {
+  if (schema.anyOf ?? schema.oneOf ?? schema.allOf) return true;
+  return isObject(schema) || schema.type === "array";
 }
 function getSchemaType(schema) {
   if (schema.nullable) {
-    if (!schema.type) return "null";
-    return `${getSchemaType({ ...schema, nullable: false })} | null`;
+    const type = getSchemaType({ ...schema, nullable: false });
+    return type === "unknown" ? "null" : `${type} | null`;
   }
+  if (schema.title) return schema.title;
   if (schema.type === "array")
-    return `array of ${getSchemaType(noRef(schema.items))}`;
+    return `array<${getSchemaType(noRef(schema.items))}>`;
   if (schema.oneOf)
     return schema.oneOf.map((one) => getSchemaType(noRef(one))).join(" | ");
   if (schema.allOf)
     return schema.allOf.map((one) => getSchemaType(noRef(one))).join(" & ");
-  if (schema.anyOf)
+  if (schema.not) return `not ${getSchemaType(noRef(schema.not))}`;
+  if (schema.anyOf) {
     return `Any properties in ${schema.anyOf.map((one) => getSchemaType(noRef(one))).join(", ")}`;
+  }
   if (schema.type) return schema.type;
   if (isObject(schema)) return "object";
-  throw new Error(`Cannot detect object type: ${JSON.stringify(schema)}`);
+  return "unknown";
 }
 
 // src/render/operation.ts
@@ -448,21 +474,30 @@ async function renderOperation(path, method, ctx, noTitle = false) {
     info.push(heading(level, group), ...parameters);
   }
   info.push(getResponseTable(method));
+  const samples = dedupe([
+    {
+      label: "cURL",
+      source: getSampleRequest(endpoint),
+      lang: "bash"
+    },
+    {
+      label: "JavaScript",
+      source: getSampleRequest2(endpoint),
+      lang: "js"
+    },
+    ...ctx.generateCodeSamples?.(endpoint) ?? [],
+    ...method["x-codeSamples"] ?? []
+  ]);
   example.push(
     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"
+      samples.map((s) => s.label),
+      samples.map(
+        (s) => ctx.renderer.Request({
+          name: s.label,
+          code: s.source,
+          language: s.lang
         })
-      ]
+      )
     )
   );
   example.push(await getResponseTabs(endpoint, method, ctx));
@@ -471,6 +506,16 @@ async function renderOperation(path, method, ctx, noTitle = false) {
     ctx.renderer.APIExample(example)
   ]);
 }
+function dedupe(samples) {
+  const set = /* @__PURE__ */ new Set();
+  const out = [];
+  for (let i = samples.length - 1; i >= 0; i--) {
+    if (set.has(samples[i].label)) continue;
+    set.add(samples[i].label);
+    out.unshift(samples[i]);
+  }
+  return out;
+}
 function getAuthSection(requirements, { document, renderer }) {
   const info = [];
   const schemas = document.components?.securitySchemes ?? {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fumadocs-openapi",
-  "version": "3.1.3",
+  "version": "3.3.0",
   "description": "Generate MDX docs for your OpenAPI spec",
   "keywords": [
     "NextJs",
@@ -20,12 +20,12 @@
     "@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",
+    "json-schema-to-typescript": "^14.1.0",
     "openapi-sampler": "^1.5.1"
   },
   "devDependencies": {
     "@types/js-yaml": "^4.0.9",
-    "@types/node": "18.17.5",
+    "@types/node": "20.14.9",
     "@types/openapi-sampler": "^1.0.3",
     "openapi-types": "^12.1.3",
     "eslint-config-custom": "0.0.0",