docusaurus-theme-openapi-docs 1.0.0

package/lib-next/theme/ApiDemoPanel/buildPostmanRequest.js

@@ -0,0 +1,310 @@
+/* ============================================================================
+ * 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 sdk from "@paloaltonetworks/postman-collection";
+// @ts-ignore
+import cloneDeep from "lodash/cloneDeep";
+
+function setQueryParams(postman, queryParams) {
+  postman.url.query.clear();
+  const qp = queryParams
+    .map((param) => {
+      if (!param.value) {
+        return undefined;
+      }
+
+      if (Array.isArray(param.value)) {
+        return new sdk.QueryParam({
+          key: param.name,
+          value: param.value.join(","),
+        });
+      } // Parameter allows empty value: "/hello?extended"
+
+      if (param.allowEmptyValue) {
+        if (param.value === "true") {
+          return new sdk.QueryParam({
+            key: param.name,
+            value: null,
+          });
+        }
+
+        return undefined;
+      }
+
+      return new sdk.QueryParam({
+        key: param.name,
+        value: param.value,
+      });
+    })
+    .filter((item) => item !== undefined);
+
+  if (qp.length > 0) {
+    postman.addQueryParams(qp);
+  }
+}
+
+function setPathParams(postman, queryParams) {
+  const source = queryParams.map((param) => {
+    return new sdk.Variable({
+      key: param.name,
+      value: param.value || `:${param.name}`,
+    });
+  });
+  postman.url.variables.assimilate(source, false);
+}
+
+function buildCookie(cookieParams) {
+  const cookies = cookieParams
+    .map((param) => {
+      if (param.value && !Array.isArray(param.value)) {
+        return new sdk.Cookie({
+          // TODO: Is this right?
+          path: "",
+          domain: "",
+          key: param.name,
+          value: param.value,
+        });
+      }
+
+      return undefined;
+    })
+    .filter((item) => item !== undefined);
+  const list = new sdk.CookieList(null, cookies);
+  return list.toString();
+}
+
+function setHeaders(postman, contentType, accept, cookie, headerParams, other) {
+  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 && !Array.isArray(param.value)) {
+      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, 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[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[1])
+        .map(([key, content]) => {
+          if (content.type !== "file" && content.value) {
+            return new sdk.QueryParam({
+              key: key,
+              value: content.value,
+            });
+          }
+
+          return undefined;
+        })
+        .filter((item) => item !== undefined);
+      clonedPostman.body.urlencoded?.assimilate(params, false);
+      return;
+    }
+
+    default:
+      return;
+  }
+} // TODO: finish these types
+
+function buildPostmanRequest(
+  postman,
+  {
+    queryParams,
+    pathParams,
+    cookieParams,
+    contentType,
+    accept,
+    headerParams,
+    body,
+    server,
+    auth,
+  }
+) {
+  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 = [];
+
+  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) {
+        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: "API_KEY_VALUE",
+        });
+        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/lib-next/theme/ApiDemoPanel/hooks.js

@@ -0,0 +1,9 @@
+/* ============================================================================
+ * 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 { useDispatch, useSelector } from "react-redux";
+export const useTypedDispatch = () => useDispatch();
+export const useTypedSelector = useSelector;

package/lib-next/theme/ApiDemoPanel/index.js

@@ -0,0 +1,110 @@
+/* ============================================================================
+ * 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 useDocusaurusContext from "@docusaurus/useDocusaurusContext"; // @ts-ignore
+// @ts-ignore
+
+import sdk from "@paloaltonetworks/postman-collection"; // @ts-ignore
+
+import { Provider } from "react-redux";
+import Accept from "./Accept";
+import { createAuth } from "./Authorization/slice";
+import Body from "./Body";
+import Curl from "./Curl";
+import MethodEndpoint from "./MethodEndpoint";
+import ParamOptions from "./ParamOptions";
+import { createPersistanceMiddleware } from "./persistanceMiddleware";
+import Response from "./Response";
+import SecuritySchemes from "./SecuritySchemes";
+import Server from "./Server";
+import { createStoreWithState } from "./store";
+import styles from "./styles.module.css";
+
+function ApiDemoPanel({ item }) {
+  const { siteConfig } = useDocusaurusContext();
+  const themeConfig = siteConfig.themeConfig;
+  const options = themeConfig.api;
+  const postman = new sdk.Request(item.postman);
+  const acceptArray = Array.from(
+    new Set(
+      Object.values(item.responses ?? {}) // @ts-ignore
+        .map((response) => Object.keys(response.content ?? {}))
+        .flat()
+    )
+  );
+  const content = item.requestBody?.content ?? {};
+  const contentTypeArray = Object.keys(content);
+  const servers = item.servers ?? [];
+  const params = {
+    path: [],
+    query: [],
+    header: [],
+    cookie: [],
+  };
+  item.parameters?.forEach((param) => {
+    // @ts-ignore
+    params[param.in].push(param);
+  });
+  const auth = createAuth({
+    security: item.security,
+    securitySchemes: item.securitySchemes,
+    options,
+  });
+  const persistanceMiddleware = createPersistanceMiddleware(options);
+  const store2 = createStoreWithState(
+    {
+      accept: {
+        value: acceptArray[0],
+        options: acceptArray,
+      },
+      contentType: {
+        value: contentTypeArray[0],
+        options: contentTypeArray,
+      },
+      server: {
+        value: servers[0],
+        options: servers,
+      },
+      response: {
+        value: undefined,
+      },
+      body: {
+        type: "empty",
+      },
+      params,
+      auth,
+    },
+    [persistanceMiddleware]
+  );
+  const { path, method } = item;
+  return (
+    <Provider store={store2}>
+      <div className={styles.apiDemoPanelContainer}>
+        <MethodEndpoint method={method} path={path} />
+
+        <SecuritySchemes />
+
+        <div className={styles.optionsPanel}>
+          <ParamOptions />
+          <Body
+            jsonRequestBodyExample={item.jsonRequestBodyExample}
+            requestBodyMetadata={item.requestBody}
+          />
+          <Accept />
+        </div>
+
+        <Server />
+
+        <Curl postman={postman} codeSamples={item["x-code-samples"] ?? []} />
+
+        <Response />
+      </div>
+    </Provider>
+  );
+}
+
+export default ApiDemoPanel;

package/lib-next/theme/ApiDemoPanel/persistanceMiddleware.js

@@ -0,0 +1,38 @@
+/* ============================================================================
+ * 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 { setAuthData, setSelectedAuth } from "./Authorization/slice";
+import { createStorage, hashArray } from "./storage-utils";
+export function createPersistanceMiddleware(options) {
+  const persistanceMiddleware = (storeAPI) => (next) => (action) => {
+    const result = next(action);
+    const state = storeAPI.getState();
+    const storage = createStorage(options?.authPersistance);
+
+    if (action.type === setAuthData.type) {
+      for (const [key, value] of Object.entries(state.auth.data)) {
+        if (Object.values(value).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
+        );
+      }
+    }
+
+    return result;
+  };
+
+  return persistanceMiddleware;
+}

package/lib-next/theme/ApiDemoPanel/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 "@paloaltonetworks/postman-collection" {
+  export = Request.sdk;
+}

package/lib-next/theme/ApiDemoPanel/storage-utils.js

@@ -0,0 +1,35 @@
+/* ============================================================================
+ * 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) {
+  function hash(message) {
+    return crypto.SHA1(message).toString();
+  }
+
+  const hashed = arr.map((item) => hash(item));
+  hashed.sort();
+  const res = hashed.join();
+  return hash(res);
+}
+export function createStorage(persistance) {
+  if (persistance === false) {
+    return {
+      getItem: () => null,
+      setItem: () => {},
+      clear: () => {},
+      key: () => null,
+      removeItem: () => {},
+      length: 0,
+    };
+  }
+
+  if (persistance === "sessionStorage") {
+    return sessionStorage;
+  }
+
+  return localStorage;
+}

package/lib-next/theme/ApiDemoPanel/store.js

@@ -0,0 +1,30 @@
+/* ============================================================================
+ * 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 { configureStore, combineReducers } from "@reduxjs/toolkit";
+import accept from "./Accept/slice";
+import auth from "./Authorization/slice";
+import body from "./Body/slice";
+import contentType from "./ContentType/slice";
+import params from "./ParamOptions/slice";
+import response from "./Response/slice";
+import server from "./Server/slice";
+const rootReducer = combineReducers({
+  accept,
+  contentType,
+  response,
+  server,
+  body,
+  params,
+  auth,
+});
+export const createStoreWithState = (preloadedState, middlewares) =>
+  configureStore({
+    reducer: rootReducer,
+    preloadedState,
+    middleware: (getDefaultMiddleware) =>
+      getDefaultMiddleware().concat(...middlewares),
+  });

package/lib-next/theme/ApiDemoPanel/styles.module.css

@@ -0,0 +1,44 @@
+:root {
+  /* VS Dark mode */
+  --openapi-monaco-background-color-dark: var(--ifm-color-gray-900);
+  --openapi-code-bright-dark: var(--ifm-color-secondary-lighter);
+  --openapi-code-dim-dark: var(--ifm-color-secondary-dark);
+  --openapi-code-blue-dark: var(--ifm-color-primary);
+  --openapi-code-green-dark: var(--ifm-color-success);
+  --openapi-code-select-dark: var(--ifm-color-secondary-lightest);
+
+  /* VS Light mode */
+  --openapi-monaco-background-color-light: var(--ifm-color-gray-100);
+  --openapi-code-bright-light: var(--ifm-color-black);
+  --openapi-code-dim-light: var(--ifm-color-black);
+  --openapi-code-blue-light: var(--ifm-color-primary);
+  --openapi-code-green-light: var(--ifm-color-success);
+  --openapi-code-select-light: var(--ifm-color-secondary-light);
+
+  --openapi-card-background-color: var(--ifm-color-gray-100);
+  --openapi-card-border-radius: var(--ifm-pre-border-radius);
+  --openapi-monaco-border-color: var(--openapi-card-background-color);
+  --openapi-input-border: var(--ifm-color-primary);
+}
+
+[data-theme="dark"] {
+  --openapi-card-background-color: var(--ifm-color-gray-900) !important;
+}
+
+.optionsPanel:empty {
+  display: none;
+}
+
+.optionsPanel {
+  background: var(--openapi-card-background-color);
+  border-radius: var(--openapi-card-border-radius);
+  color: var(--ifm-pre-color);
+  line-height: var(--ifm-pre-line-height);
+  margin-bottom: var(--ifm-spacing-vertical);
+  margin-top: 0;
+  overflow: auto;
+  padding: var(--ifm-pre-padding);
+
+  /* hack for view calculation when monaco is hidden */
+  position: relative;
+}