docusaurus-theme-openapi-docs 0.0.0-1000

package/src/theme/ApiExplorer/buildPostmanRequest.ts

@@ -0,0 +1,526 @@
+/* ============================================================================
+ * Copyright (c) Palo Alto Networks
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ * ========================================================================== */
+
+import { AuthState, Scheme } from "@theme/ApiExplorer/Authorization/slice";
+import { Body, Content } from "@theme/ApiExplorer/Body/slice";
+import {
+  ParameterObject,
+  ServerObject,
+} from "docusaurus-plugin-openapi-docs/src/openapi/types";
+import cloneDeep from "lodash/cloneDeep";
+import sdk from "postman-collection";
+
+type Param = {
+  value?: string | string[];
+} & ParameterObject;
+
+function setQueryParams(postman: sdk.Request, queryParams: Param[]) {
+  postman.url.query.clear();
+
+  const qp = queryParams
+    .map((param) => {
+      if (!param.value) {
+        return undefined;
+      }
+
+      // Handle array values
+      if (Array.isArray(param.value)) {
+        if (param.style === "spaceDelimited") {
+          return new sdk.QueryParam({
+            key: param.name,
+            value: param.value.join(" "),
+          });
+        } else if (param.style === "pipeDelimited") {
+          return new sdk.QueryParam({
+            key: param.name,
+            value: param.value.join("|"),
+          });
+        } else if (param.explode) {
+          return param.value.map(
+            (val) =>
+              new sdk.QueryParam({
+                key: param.name,
+                value: val,
+              })
+          );
+        } else {
+          return new sdk.QueryParam({
+            key: param.name,
+            value: param.value.join(","),
+          });
+        }
+      }
+
+      const decodedValue = decodeURI(param.value);
+      const tryJson = () => {
+        try {
+          return JSON.parse(decodedValue);
+        } catch (e) {
+          return false;
+        }
+      };
+
+      const jsonResult = tryJson();
+
+      // Handle object values
+      if (jsonResult && typeof jsonResult === "object") {
+        if (param.style === "deepObject") {
+          return Object.entries(jsonResult).map(
+            ([key, val]) =>
+              new sdk.QueryParam({
+                key: `${param.name}[${key}]`,
+                value: val,
+              })
+          );
+        } else if (param.explode) {
+          return Object.entries(jsonResult).map(
+            ([key, val]) =>
+              new sdk.QueryParam({
+                key: key,
+                value: val,
+              })
+          );
+        } else {
+          return new sdk.QueryParam({
+            key: param.name,
+            value: Object.entries(jsonResult)
+              .map(([key, val]) => `${key},${val}`)
+              .join(","),
+          });
+        }
+      }
+
+      // Handle boolean values
+      if (typeof decodedValue === "boolean") {
+        return new sdk.QueryParam({
+          key: param.name,
+          value: decodedValue ? "true" : "false",
+        });
+      }
+
+      // Parameter allows empty value: "/hello?extended"
+      if (param.allowEmptyValue) {
+        if (decodedValue === "true") {
+          return new sdk.QueryParam({
+            key: param.name,
+            value: null,
+          });
+        }
+        return undefined;
+      }
+
+      return new sdk.QueryParam({
+        key: param.name,
+        value: param.value,
+      });
+    })
+    .flat() // Flatten the array in case of nested arrays from map
+    .filter((item) => item !== undefined);
+
+  if (qp.length > 0) {
+    postman.addQueryParams(qp);
+  }
+}
+
+function setPathParams(postman: sdk.Request, pathParams: Param[]) {
+  // Map through the path parameters
+  const source = pathParams.map((param) => {
+    if (!param.value) {
+      return undefined;
+    }
+
+    let serializedValue;
+
+    // Handle different styles
+    if (Array.isArray(param.value)) {
+      if (param.style === "label") {
+        serializedValue = `.${param.value.join(".")}`;
+      } else if (param.style === "matrix") {
+        serializedValue = `;${param.name}=${param.value.join(";")}`;
+      } else {
+        serializedValue = param.value.join(",");
+      }
+      return new sdk.Variable({
+        key: param.name,
+        value: serializedValue,
+      });
+    }
+
+    const decodedValue = decodeURI(param.value);
+    const tryJson = () => {
+      try {
+        return JSON.parse(decodedValue);
+      } catch (e) {
+        return false;
+      }
+    };
+
+    const jsonResult = tryJson();
+
+    if (typeof jsonResult === "object") {
+      if (param.style === "matrix") {
+        serializedValue = Object.entries(jsonResult)
+          .map(([key, val]) => `;${key}=${val}`)
+          .join("");
+      } else {
+        serializedValue = Object.entries(jsonResult)
+          .map(([key, val]) => `${key}=${val}`)
+          .join(",");
+      }
+    } else {
+      serializedValue = decodedValue || `:${param.name}`;
+    }
+
+    return new sdk.Variable({
+      key: param.name,
+      value: serializedValue,
+    });
+  });
+
+  postman.url.variables.assimilate(source, false);
+}
+
+function buildCookie(cookieParams: Param[]) {
+  const cookies = cookieParams
+    .map((param) => {
+      if (param.value) {
+        const decodedValue = decodeURI(param.value as string);
+        const tryJson = () => {
+          try {
+            return JSON.parse(decodedValue);
+          } catch (e) {
+            return false;
+          }
+        };
+
+        const jsonResult = tryJson();
+        if (typeof jsonResult === "object") {
+          if (param.style === "form") {
+            // Handle form style
+            if (param.explode) {
+              // Serialize each key-value pair as a separate cookie
+              return Object.entries(jsonResult).map(
+                ([key, val]) =>
+                  new sdk.Cookie({
+                    key: key,
+                    value: val,
+                  })
+              );
+            } else {
+              // Serialize the object as a single cookie with key-value pairs joined by commas
+              return new sdk.Cookie({
+                key: param.name,
+                value: Object.entries(jsonResult)
+                  .map(([key, val]) => `${key},${val}`)
+                  .join(","),
+              });
+            }
+          }
+        } else {
+          // Handle scalar values
+          return new sdk.Cookie({
+            key: param.name,
+            value: param.value,
+          });
+        }
+      }
+      return undefined;
+    })
+    .flat() // Flatten the array in case of nested arrays from map
+    .filter((item) => item !== undefined);
+
+  const list = new sdk.CookieList(null, cookies);
+  return list.toString();
+}
+
+function setHeaders(
+  postman: sdk.Request,
+  contentType: string,
+  accept: string,
+  cookie: string,
+  headerParams: Param[],
+  other: { key: string; value: string }[]
+) {
+  postman.headers.clear();
+
+  if (contentType) {
+    postman.addHeader({ key: "Content-Type", value: contentType });
+  }
+
+  if (accept) {
+    postman.addHeader({ key: "Accept", value: accept });
+  }
+
+  headerParams.forEach((param) => {
+    if (param.value) {
+      const decodedValue = decodeURI(param.value as string);
+      const tryJson = () => {
+        try {
+          return JSON.parse(decodedValue);
+        } catch (e) {
+          return false;
+        }
+      };
+
+      const jsonResult = tryJson();
+      if (Array.isArray(param.value)) {
+        if (param.style === "simple") {
+          if (param.explode) {
+            // Each item in the array is a separate header
+            jsonResult.forEach((val: any) => {
+              postman.addHeader({ key: param.name, value: val });
+            });
+          } else {
+            // Array values are joined by commas
+            postman.addHeader({
+              key: param.name,
+              value: param.value.join(","),
+            });
+          }
+        }
+      } else if (typeof jsonResult === "object") {
+        if (param.style === "simple") {
+          if (param.explode) {
+            // Each key-value pair in the object is a separate header
+            Object.entries(jsonResult).forEach(([key, val]) => {
+              postman.addHeader({ key: param.name, value: `${key}=${val}` });
+            });
+          } else {
+            // Object is serialized as a single header with key-value pairs joined by commas
+            postman.addHeader({
+              key: param.name,
+              value: Object.entries(jsonResult)
+                .map(([key, val]) => `${key},${val}`)
+                .join(","),
+            });
+          }
+        }
+      } else {
+        // Handle scalar values
+        postman.addHeader({ key: param.name, value: param.value });
+      }
+    }
+  });
+
+  other.forEach((header) => {
+    postman.addHeader(header);
+  });
+
+  if (cookie) {
+    postman.addHeader({ key: "Cookie", value: cookie });
+  }
+}
+
+// TODO: this is all a bit hacky
+function setBody(clonedPostman: sdk.Request, body: Body) {
+  if (clonedPostman.body === undefined) {
+    return;
+  }
+
+  if (body.type === "empty") {
+    clonedPostman.body = undefined;
+    return;
+  }
+
+  if (body.type === "raw" && body.content?.type === "file") {
+    // treat it like file.
+    clonedPostman.body.mode = "file";
+    clonedPostman.body.file = { src: body.content.value.src };
+    return;
+  }
+
+  switch (clonedPostman.body.mode) {
+    case "raw": {
+      // check file even though it should already be set from above
+      if (body.type !== "raw" || body.content?.type === "file") {
+        clonedPostman.body = undefined;
+        return;
+      }
+      clonedPostman.body.raw = body.content?.value ?? "";
+      return;
+    }
+    case "formdata": {
+      clonedPostman.body.formdata?.clear();
+      if (body.type !== "form") {
+        // treat it like raw.
+        clonedPostman.body.mode = "raw";
+        clonedPostman.body.raw = `${body.content?.value}`;
+        return;
+      }
+      const params = Object.entries(body.content)
+        .filter((entry): entry is [string, NonNullable<Content>] => !!entry[1])
+        .map(([key, content]) => {
+          if (content.type === "file") {
+            return new sdk.FormParam({ key: key, ...content });
+          }
+          return new sdk.FormParam({ key: key, value: content.value });
+        });
+      clonedPostman.body.formdata?.assimilate(params, false);
+      return;
+    }
+    case "urlencoded": {
+      clonedPostman.body.urlencoded?.clear();
+      if (body.type !== "form") {
+        // treat it like raw.
+        clonedPostman.body.mode = "raw";
+        clonedPostman.body.raw = `${body.content?.value}`;
+        return;
+      }
+      const params = Object.entries(body.content)
+        .filter((entry): entry is [string, NonNullable<Content>] => !!entry[1])
+        .map(([key, content]) => {
+          if (content.type !== "file" && content.value) {
+            return new sdk.QueryParam({ key: key, value: content.value });
+          }
+          return undefined;
+        })
+        .filter((item): item is sdk.QueryParam => item !== undefined);
+      clonedPostman.body.urlencoded?.assimilate(params, false);
+      return;
+    }
+    default:
+      return;
+  }
+}
+
+// TODO: finish these types
+interface Options {
+  server?: ServerObject;
+  queryParams: Param[];
+  pathParams: Param[];
+  cookieParams: Param[];
+  headerParams: Param[];
+  contentType: string;
+  accept: string;
+  body: Body;
+  auth: AuthState;
+}
+
+function buildPostmanRequest(
+  postman: sdk.Request,
+  {
+    queryParams,
+    pathParams,
+    cookieParams,
+    contentType,
+    accept,
+    headerParams,
+    body,
+    server,
+    auth,
+  }: Options
+) {
+  const clonedPostman = cloneDeep(postman);
+
+  clonedPostman.url.protocol = undefined;
+  clonedPostman.url.host = [window.location.origin];
+
+  if (server) {
+    let url = server.url.replace(/\/$/, "");
+    const variables = server.variables;
+    if (variables) {
+      Object.keys(variables).forEach((variable) => {
+        url = url.replace(`{${variable}}`, variables[variable].default);
+      });
+    }
+    clonedPostman.url.host = [url];
+  }
+
+  setQueryParams(clonedPostman, queryParams);
+  setPathParams(clonedPostman, pathParams);
+
+  const cookie = buildCookie(cookieParams);
+  let otherHeaders = [];
+
+  let selectedAuth: Scheme[] = [];
+  if (auth.selected !== undefined) {
+    selectedAuth = auth.options[auth.selected];
+  }
+
+  for (const a of selectedAuth) {
+    // Bearer Auth
+    if (a.type === "http" && a.scheme === "bearer") {
+      const { token } = auth.data[a.key];
+      if (token === undefined) {
+        otherHeaders.push({
+          key: "Authorization",
+          value: "Bearer <TOKEN>",
+        });
+        continue;
+      }
+      otherHeaders.push({
+        key: "Authorization",
+        value: `Bearer ${token}`,
+      });
+      continue;
+    }
+
+    if (a.type === "oauth2") {
+      let token;
+      if (auth.data[a.key]) {
+        token = auth.data[a.key].token;
+      }
+      if (token === undefined) {
+        otherHeaders.push({
+          key: "Authorization",
+          value: "Bearer <TOKEN>",
+        });
+        continue;
+      }
+      otherHeaders.push({
+        key: "Authorization",
+        value: `Bearer ${token}`,
+      });
+      continue;
+    }
+
+    // Basic Auth
+    if (a.type === "http" && a.scheme === "basic") {
+      const { username, password } = auth.data[a.key];
+      if (username === undefined || password === undefined) {
+        continue;
+      }
+      otherHeaders.push({
+        key: "Authorization",
+        value: `Basic ${window.btoa(`${username}:${password}`)}`,
+      });
+      continue;
+    }
+
+    // API Key
+    if (a.type === "apiKey" && a.in === "header") {
+      const { apiKey } = auth.data[a.key];
+      if (apiKey === undefined) {
+        otherHeaders.push({
+          key: a.name,
+          value: `<${a.name ?? a.type}>`,
+        });
+        continue;
+      }
+      otherHeaders.push({
+        key: a.name,
+        value: apiKey,
+      });
+      continue;
+    }
+  }
+
+  setHeaders(
+    clonedPostman,
+    contentType,
+    accept,
+    cookie,
+    headerParams,
+    otherHeaders
+  );
+
+  setBody(clonedPostman, body);
+
+  return clonedPostman;
+}
+
+export default buildPostmanRequest;

package/src/theme/ApiExplorer/index.tsx

@@ -0,0 +1,41 @@
+/* ============================================================================
+ * Copyright (c) Palo Alto Networks
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ * ========================================================================== */
+
+import React from "react";
+
+import CodeSnippets from "@theme/ApiExplorer/CodeSnippets";
+import Request from "@theme/ApiExplorer/Request";
+import Response from "@theme/ApiExplorer/Response";
+import SecuritySchemes from "@theme/ApiExplorer/SecuritySchemes";
+import { ApiItem } from "docusaurus-plugin-openapi-docs/src/types";
+import sdk from "postman-collection";
+
+function ApiExplorer({
+  item,
+  infoPath,
+}: {
+  item: NonNullable<ApiItem>;
+  infoPath: string;
+}) {
+  const postman = new sdk.Request(item.postman);
+
+  return (
+    <>
+      <SecuritySchemes infoPath={infoPath} />
+      {item.method !== "event" && (
+        <CodeSnippets
+          postman={postman}
+          codeSamples={(item as any)["x-codeSamples"] ?? []}
+        />
+      )}
+      <Request item={item} />
+      <Response item={item} />
+    </>
+  );
+}
+
+export default ApiExplorer;

package/src/theme/ApiExplorer/persistanceMiddleware.ts

@@ -0,0 +1,71 @@
+/* ============================================================================
+ * Copyright (c) Palo Alto Networks
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ * ========================================================================== */
+
+import { Middleware } from "@reduxjs/toolkit";
+import {
+  setAuthData,
+  setSelectedAuth,
+} from "@theme/ApiExplorer/Authorization/slice";
+import { AppDispatch, RootState } from "@theme/ApiItem/store";
+/* eslint-disable import/no-extraneous-dependencies*/
+import { ThemeConfig } from "docusaurus-theme-openapi-docs/src/types";
+
+import { createStorage, hashArray } from "./storage-utils";
+
+export function createPersistanceMiddleware(options: ThemeConfig["api"]) {
+  const persistanceMiddleware: Middleware<{}, RootState, AppDispatch> =
+    (storeAPI) => (next) => (action) => {
+      const result = next(action);
+
+      const state = storeAPI.getState();
+
+      const storage = createStorage("sessionStorage");
+
+      if (action.type === setAuthData.type) {
+        for (const [key, value] of Object.entries(state.auth.data)) {
+          if (Object.values(value as any).filter(Boolean).length > 0) {
+            storage.setItem(key, JSON.stringify(value));
+          } else {
+            storage.removeItem(key);
+          }
+        }
+      }
+
+      if (action.type === setSelectedAuth.type) {
+        if (state.auth.selected) {
+          storage.setItem(
+            hashArray(Object.keys(state.auth.options)),
+            state.auth.selected
+          );
+        }
+      }
+
+      // TODO: determine way to rehydrate without flashing
+      if (action.type === "contentType/setContentType") {
+        storage.setItem("contentType", action.payload);
+      }
+
+      if (action.type === "accept/setAccept") {
+        storage.setItem("accept", action.payload);
+      }
+
+      if (action.type === "server/setServer") {
+        storage.setItem("server", action.payload);
+      }
+
+      if (action.type === "server/setServerVariable") {
+        const server = storage.getItem("server") ?? "{}";
+        const variables = JSON.parse(action.payload);
+        let serverObject = JSON.parse(server);
+        serverObject.variables[variables.key].default = variables.value;
+        storage.setItem("server", JSON.stringify(serverObject));
+      }
+
+      return result;
+    };
+  return persistanceMiddleware;
+}

package/src/theme/ApiExplorer/postman-collection.d.ts

@@ -0,0 +1,10 @@
+/* ============================================================================
+ * Copyright (c) Palo Alto Networks
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ * ========================================================================== */
+
+declare module "postman-collection" {
+  export = Request.sdk;
+}

package/src/theme/ApiExplorer/react-modal.d.ts

@@ -0,0 +1,8 @@
+/* ============================================================================
+ * Copyright (c) Palo Alto Networks
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ * ========================================================================== */
+
+declare module "react-modal";

package/src/theme/ApiExplorer/storage-utils.ts

@@ -0,0 +1,39 @@
+/* ============================================================================
+ * Copyright (c) Palo Alto Networks
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ * ========================================================================== */
+
+import crypto from "crypto-js";
+
+export function hashArray(arr: string[]) {
+  function hash(message: string) {
+    return crypto.SHA1(message).toString();
+  }
+  const hashed = arr.map((item) => hash(item));
+  hashed.sort();
+  const res = hashed.join();
+  return hash(res);
+}
+
+type Persistance = false | "localStorage" | "sessionStorage" | undefined;
+
+export function createStorage(persistance: Persistance): Storage {
+  if (persistance === false) {
+    return {
+      getItem: () => null,
+      setItem: () => {},
+      clear: () => {},
+      key: () => null,
+      removeItem: () => {},
+      length: 0,
+    };
+  }
+
+  if (persistance === "sessionStorage") {
+    return sessionStorage;
+  }
+
+  return localStorage;
+}