fumadocs-openapi 3.0.0 → 3.1.0

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;
@@ -97,9 +104,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 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

@@ -89,7 +89,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 +119,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 +128,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 +169,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 +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
@@ -345,12 +376,17 @@ function getSchemaType(schema) {
 
 // src/render/operation.ts
 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();
@@ -403,7 +439,21 @@ async function renderOperation(path, method, ctx) {
   }
   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 +461,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 +542,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);
@@ -489,6 +606,7 @@ async function generateTags(pathOrDocument, options = {}) {
 }
 function getContext(document, options) {
   return {
+    document,
     renderer: {
       ...defaultRenderer,
       ...options.renderer

package/package.json

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