docusaurus-theme-openapi-docs 1.0.0

package/src/theme/ApiDemoPanel/buildPostmanRequest.ts

@@ -0,0 +1,307 @@
+/* ============================================================================
+ * 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";
+import {
+  ParameterObject,
+  ServerObject,
+  // @ts-ignore
+} from "docusaurus-plugin-openapi-docs/src/openapi/types";
+// @ts-ignore
+import cloneDeep from "lodash/cloneDeep";
+
+import { AuthState, Scheme } from "./Authorization/slice";
+import { Body, Content } from "./Body/slice";
+
+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;
+      }
+
+      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 is sdk.QueryParam => item !== undefined);
+
+  if (qp.length > 0) {
+    postman.addQueryParams(qp);
+  }
+}
+
+function setPathParams(postman: sdk.Request, queryParams: Param[]) {
+  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: Param[]) {
+  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 is sdk.Cookie => 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 && !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: 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) {
+        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/src/theme/ApiDemoPanel/hooks.ts

@@ -0,0 +1,13 @@
+/* ============================================================================
+ * 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 { TypedUseSelectorHook, useDispatch, useSelector } from "react-redux";
+
+import type { RootState, AppDispatch } from "./store";
+
+export const useTypedDispatch = () => useDispatch<AppDispatch>();
+export const useTypedSelector: TypedUseSelectorHook<RootState> = useSelector;

package/src/theme/ApiDemoPanel/index.tsx

@@ -0,0 +1,118 @@
+/* ============================================================================
+ * 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 { Metadata } from "@theme/ApiItem";
+import { ParameterObject } from "docusaurus-plugin-openapi-docs/src/openapi/types";
+import { Provider } from "react-redux";
+
+import { ThemeConfig } from "../../types";
+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 }: { item: NonNullable<Metadata["api"]> }) {
+  const { siteConfig } = useDocusaurusContext();
+  const themeConfig = siteConfig.themeConfig as 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: [] as ParameterObject[],
+    query: [] as ParameterObject[],
+    header: [] as ParameterObject[],
+    cookie: [] as ParameterObject[],
+  };
+
+  item.parameters?.forEach((param: { in: string | number }) => {
+    // @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 as any)["x-code-samples"] ?? []}
+        />
+
+        <Response />
+      </div>
+    </Provider>
+  );
+}
+
+export default ApiDemoPanel;

package/src/theme/ApiDemoPanel/persistanceMiddleware.ts

@@ -0,0 +1,46 @@
+/* ============================================================================
+ * 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 { ThemeConfig } from "../../types";
+import { setAuthData, setSelectedAuth } from "./Authorization/slice";
+import { createStorage, hashArray } from "./storage-utils";
+import { AppDispatch, RootState } from "./store";
+
+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(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/src/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/src/theme/ApiDemoPanel/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;
+}

package/src/theme/ApiDemoPanel/store.ts

@@ -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 { 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 type RootState = ReturnType<typeof rootReducer>;
+
+export const createStoreWithState = (
+  preloadedState: RootState,
+  middlewares: any[]
+) =>
+  configureStore({
+    reducer: rootReducer,
+    preloadedState,
+    middleware: (getDefaultMiddleware) =>
+      getDefaultMiddleware().concat(...middlewares),
+  });
+
+export type AppDispatch = ReturnType<typeof createStoreWithState>["dispatch"];

package/src/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;
+}