fumadocs-openapi 3.0.0 → 3.1.1

package/dist/index.d.ts

@@ -19,6 +19,11 @@ interface PropertyProps {
 interface ObjectCollapsibleProps {
     name: string;
 }
+interface RequestProps {
+    language: string;
+    name: string;
+    code: string;
+}
 interface Renderer {
     Root: (child: string[]) => string;
     API: (child: string[]) => string;
@@ -26,6 +31,8 @@ interface Renderer {
     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;
@@ -57,7 +64,12 @@ interface GenerateTagOutput {
     tag: string;
     content: string;
 }
+interface GenerateOperationOutput {
+    id: string;
+    content: string;
+}
 declare function generate(pathOrDocument: string | OpenAPIV3.Document, options?: GenerateOptions): Promise<string>;
+declare function generateOperations(pathOrDocument: string | OpenAPIV3.Document, options?: GenerateOptions): Promise<GenerateOperationOutput[]>;
 declare function generateTags(pathOrDocument: string | OpenAPIV3.Document, options?: GenerateOptions): Promise<GenerateTagOutput[]>;
 
 interface Config extends GenerateOptions {
@@ -76,7 +88,7 @@ interface Config extends GenerateOptions {
      *
      * @defaultValue file
      */
-    per?: 'tag' | 'file';
+    per?: 'tag' | 'file' | 'operation';
     /**
      * Specify name for output file
      */
@@ -97,9 +109,10 @@ interface MethodInformation extends OpenAPIV3.OperationObject {
 }
 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 GenerateOptions, type GenerateTagOutput, type MethodInformation, type ObjectCollapsibleProps, type PropertyProps, type RenderContext, type Renderer, type ResponseProps, type ResponsesProps, type RouteInformation, createElement, defaultRenderer, generate, generateFiles, generateTags };
+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

@@ -72,6 +72,9 @@ function codeblock({ language, title }, child) {
     "```"
   ].join("\n");
 }
+function heading(depth, child) {
+  return `${"#".repeat(depth)} ${child.trim()}`;
+}
 
 // src/render/renderer.ts
 var defaultRenderer = {
@@ -89,7 +92,9 @@ var defaultRenderer = {
     codeblock({ language: "ts" }, code)
   ),
   Property: (props, child) => createElement("Property", props, ...child),
-  ObjectCollapsible: (props, child) => createElement("ObjectCollapsible", 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/render/page.ts
@@ -117,10 +122,7 @@ ${finalImports}
 ${Root(content)}`;
 }
 
-// src/samples/index.ts
-import { sample } from "openapi-sampler";
-
-// src/utils.ts
+// src/utils/schema.ts
 function noRef(v) {
   return v;
 }
@@ -129,11 +131,20 @@ 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
+// 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 = {};
@@ -161,33 +172,28 @@ function createEndpoint(path, method, baseUrl) {
   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
     );
@@ -195,38 +201,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
@@ -344,18 +378,24 @@ function getSchemaType(schema) {
 }
 
 // src/render/operation.ts
-async function renderOperation(path, method, ctx) {
+async function renderOperation(path, method, ctx, noTitle = false) {
+  let level = 2;
+  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 (title && !noTitle) info.push(heading(level++, title));
   if (method.description) info.push(p(method.description));
-  const body = noRef(method.requestBody);
+  if (security) {
+    info.push(heading(level, "Authorization"));
+    info.push(getAuthSection(security, ctx));
+  }
   if (body) {
     const bodySchema = getPreferredMedia(body.content)?.schema;
     if (!bodySchema) throw new Error();
     info.push(
-      `### Request Body${!body.required ? " (Optional)" : ""}`,
+      heading(level, `Request Body ${!body.required ? "(Optional)" : ""}`),
       p(body.description),
       schemaElement("body", noRef(bodySchema), {
         parseObject: true,
@@ -399,11 +439,25 @@ async function renderOperation(path, method, ctx) {
     parameterGroups.set(groupName, group);
   }
   for (const [group, parameters] of Array.from(parameterGroups.entries())) {
-    info.push(`### ${group}`, ...parameters);
+    info.push(heading(level, group), ...parameters);
   }
   info.push(getResponseTable(method));
   example.push(
-    codeblock({ language: "bash", title: "curl" }, getSampleRequest(endpoint))
+    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([
@@ -411,6 +465,73 @@ async function renderOperation(path, method, ctx) {
     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 = [];
   table.push(`| Status code | Description |`);
@@ -425,7 +546,7 @@ async function getResponseTabs(endpoint, operation, { renderer }) {
   const child = [];
   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);
@@ -467,6 +588,29 @@ async function generate(pathOrDocument, options = {}) {
     options
   );
 }
+async function generateOperations(pathOrDocument, options = {}) {
+  const document = await Parser.dereference(pathOrDocument);
+  const routes = buildRoutes(document).get("all") ?? [];
+  const ctx = getContext(document, options);
+  return await Promise.all(
+    routes.flatMap((route) => {
+      return route.methods.map(async (method) => {
+        const content = renderPage(
+          method.summary ?? method.method,
+          method.description,
+          [await renderOperation(route.path, method, ctx, true)],
+          options
+        );
+        if (!method.operationId)
+          throw new Error("Operation ID is required for generating docs.");
+        return {
+          id: method.operationId,
+          content
+        };
+      });
+    })
+  );
+}
 async function generateTags(pathOrDocument, options = {}) {
   const document = await Parser.dereference(pathOrDocument);
   const tags = Array.from(buildRoutes(document).entries());
@@ -489,6 +633,7 @@ async function generateTags(pathOrDocument, options = {}) {
 }
 function getContext(document, options) {
   return {
+    document,
     renderer: {
       ...defaultRenderer,
       ...options.renderer
@@ -522,10 +667,24 @@ async function generateFiles({
         console.log(`Generated: ${outPath}`);
         return;
       }
+      if (per === "operation") {
+        const results2 = await generateOperations(path, options);
+        await Promise.all(
+          results2.map(async (result) => {
+            const outPath = join(
+              outputDir,
+              filename,
+              `${getName(result.id)}.mdx`
+            );
+            await write(outPath, result.content);
+            console.log(`Generated: ${outPath}`);
+          })
+        );
+      }
       const results = await generateTags(path, options);
       for (const result of results) {
         let tagName = result.tag;
-        tagName = nameFn?.("tag", tagName) ?? tagName.toLowerCase().replace(/\s+/g, "-");
+        tagName = nameFn?.("tag", tagName) ?? getName(tagName);
         const outPath = join(outputDir, filename, `${tagName}.mdx`);
         await write(outPath, result.content);
         console.log(`Generated: ${outPath}`);
@@ -533,6 +692,12 @@ async function generateFiles({
     })
   );
 }
+function getName(s) {
+  return s.replace(
+    /[A-Z]/g,
+    (match, idx) => idx === 0 ? match : `-${match.toLowerCase()}`
+  ).replace(/\s+/g, "-").toLowerCase();
+}
 async function write(path, content) {
   await mkdir(dirname(path), { recursive: true });
   await writeFile(path, content);
@@ -542,5 +707,6 @@ export {
   defaultRenderer,
   generate,
   generateFiles,
+  generateOperations,
   generateTags
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fumadocs-openapi",
-  "version": "3.0.0",
+  "version": "3.1.1",
   "description": "Generate MDX docs for your OpenAPI spec",
   "keywords": [
     "NextJs",