docusaurus-theme-openapi-docs 0.0.0-1000

package/src/theme/ApiExplorer/ApiCodeBlock/index.tsx

@@ -0,0 +1,45 @@
+/* ============================================================================
+ * 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, { isValidElement, ReactNode } from "react";
+
+import { CodeBlockProps } from "@docusaurus/theme-common/internal";
+import useIsBrowser from "@docusaurus/useIsBrowser";
+import ElementContent from "@theme/ApiExplorer/ApiCodeBlock/Content/Element";
+import StringContent from "@theme/ApiExplorer/ApiCodeBlock/Content/String";
+
+/**
+ * Best attempt to make the children a plain string so it is copyable. If there
+ * are react elements, we will not be able to copy the content, and it will
+ * return `children` as-is; otherwise, it concatenates the string children
+ * together.
+ */
+function maybeStringifyChildren(children: ReactNode): ReactNode {
+  if (React.Children.toArray(children).some((el) => isValidElement(el))) {
+    return children;
+  }
+  // The children is now guaranteed to be one/more plain strings
+  return Array.isArray(children) ? children.join("") : (children as string);
+}
+export default function ApiCodeBlock({
+  children: rawChildren,
+  ...props
+}: CodeBlockProps) {
+  // The Prism theme on SSR is always the default theme but the site theme can
+  // be in a different mode. React hydration doesn't update DOM styles that come
+  // from SSR. Hence force a re-render after mounting to apply the current
+  // relevant styles.
+  const isBrowser = useIsBrowser();
+  const children = maybeStringifyChildren(rawChildren);
+  const CodeBlockComp =
+    typeof children === "string" ? StringContent : ElementContent;
+  return (
+    <CodeBlockComp key={String(isBrowser)} {...props}>
+      {children as string}
+    </CodeBlockComp>
+  );
+}

package/src/theme/ApiExplorer/Authorization/auth-types.ts

@@ -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.
+ * ========================================================================== */
+
+export function getAuthDataKeys(security: { [key: string]: any }) {
+  // Bearer Auth
+  if (security.type === "http" && security.scheme === "bearer") {
+    return ["token"];
+  }
+
+  if (security.type === "oauth2") {
+    return ["token"];
+  }
+
+  // Basic Auth
+  if (security.type === "http" && security.scheme === "basic") {
+    return ["username", "password"];
+  }
+
+  // API Auth
+  if (security.type === "apiKey") {
+    return ["apiKey"];
+  }
+
+  // none
+  return [];
+}

package/src/theme/ApiExplorer/Authorization/index.tsx

@@ -0,0 +1,158 @@
+/* ============================================================================
+ * 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 FormItem from "@theme/ApiExplorer/FormItem";
+import FormSelect from "@theme/ApiExplorer/FormSelect";
+import FormTextInput from "@theme/ApiExplorer/FormTextInput";
+import { useTypedDispatch, useTypedSelector } from "@theme/ApiItem/hooks";
+
+import { setAuthData, setSelectedAuth } from "./slice";
+
+function Authorization() {
+  const data = useTypedSelector((state: any) => state.auth.data);
+  const options = useTypedSelector((state: any) => state.auth.options);
+  const selected = useTypedSelector((state: any) => state.auth.selected);
+
+  const dispatch = useTypedDispatch();
+
+  if (selected === undefined) {
+    return null;
+  }
+
+  const selectedAuth = options[selected];
+
+  const optionKeys = Object.keys(options);
+
+  return (
+    <div>
+      {optionKeys.length > 1 && (
+        <FormItem label="Security Scheme">
+          <FormSelect
+            options={optionKeys}
+            value={selected}
+            onChange={(e: React.ChangeEvent<HTMLInputElement>) => {
+              dispatch(setSelectedAuth(e.target.value));
+            }}
+          />
+        </FormItem>
+      )}
+      {selectedAuth.map((a: any) => {
+        if (a.type === "http" && a.scheme === "bearer") {
+          return (
+            <FormItem label="Bearer Token" key={a.key + "-bearer"}>
+              <FormTextInput
+                placeholder="Bearer Token"
+                password
+                value={data[a.key].token ?? ""}
+                onChange={(e: React.ChangeEvent<HTMLInputElement>) => {
+                  const value = e.target.value;
+                  dispatch(
+                    setAuthData({
+                      scheme: a.key,
+                      key: "token",
+                      value: value ? value : undefined,
+                    })
+                  );
+                }}
+              />
+            </FormItem>
+          );
+        }
+
+        if (a.type === "oauth2") {
+          return (
+            <FormItem label="Bearer Token" key={a.key + "-oauth2"}>
+              <FormTextInput
+                placeholder="Bearer Token"
+                password
+                value={data[a.key].token ?? ""}
+                onChange={(e: React.ChangeEvent<HTMLInputElement>) => {
+                  const value = e.target.value;
+                  dispatch(
+                    setAuthData({
+                      scheme: a.key,
+                      key: "token",
+                      value: value ? value : undefined,
+                    })
+                  );
+                }}
+              />
+            </FormItem>
+          );
+        }
+
+        if (a.type === "http" && a.scheme === "basic") {
+          return (
+            <React.Fragment key={a.key + "-basic"}>
+              <FormItem label="Username">
+                <FormTextInput
+                  placeholder="Username"
+                  value={data[a.key].username ?? ""}
+                  onChange={(e: React.ChangeEvent<HTMLInputElement>) => {
+                    const value = e.target.value;
+                    dispatch(
+                      setAuthData({
+                        scheme: a.key,
+                        key: "username",
+                        value: value ? value : undefined,
+                      })
+                    );
+                  }}
+                />
+              </FormItem>
+              <FormItem label="Password">
+                <FormTextInput
+                  placeholder="Password"
+                  password
+                  value={data[a.key].password ?? ""}
+                  onChange={(e: React.ChangeEvent<HTMLInputElement>) => {
+                    const value = e.target.value;
+                    dispatch(
+                      setAuthData({
+                        scheme: a.key,
+                        key: "password",
+                        value: value ? value : undefined,
+                      })
+                    );
+                  }}
+                />
+              </FormItem>
+            </React.Fragment>
+          );
+        }
+
+        if (a.type === "apiKey") {
+          return (
+            <FormItem label={`${a.key}`} key={a.key + "-apikey"}>
+              <FormTextInput
+                placeholder={`${a.key}`}
+                password
+                value={data[a.key].apiKey ?? ""}
+                onChange={(e: React.ChangeEvent<HTMLInputElement>) => {
+                  const value = e.target.value;
+                  dispatch(
+                    setAuthData({
+                      scheme: a.key,
+                      key: "apiKey",
+                      value: value ? value : undefined,
+                    })
+                  );
+                }}
+              />
+            </FormItem>
+          );
+        }
+
+        return null;
+      })}
+    </div>
+  );
+}
+
+export default Authorization;

package/src/theme/ApiExplorer/Authorization/slice.ts

@@ -0,0 +1,146 @@
+/* ============================================================================
+ * 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 { createSlice, PayloadAction } from "@reduxjs/toolkit";
+import { createStorage, hashArray } from "@theme/ApiExplorer/storage-utils";
+import {
+  SecurityRequirementObject,
+  SecuritySchemeObject,
+} from "docusaurus-plugin-openapi-docs/src/openapi/types";
+/* eslint-disable import/no-extraneous-dependencies*/
+import { ThemeConfig } from "docusaurus-theme-openapi-docs/src/types";
+
+import { getAuthDataKeys } from "./auth-types";
+
+// The global definitions
+// "securitySchemes": {
+//   "BearerAuth": { "type": "http", "scheme": "BeAreR" },
+//   "BasicAuth": { "type": "http", "scheme": "basic" }
+// },
+
+// The operation level requirements
+// "security": [
+//   { "BearerAuth": [] },
+//   { "BearerAuth": [], "BasicAuth": [] }
+// ],
+
+// SLICE_STATE
+// data:
+//   BearerAuth:
+//     token=xxx
+//   BasicAuth:
+//     username=xxx
+//     password=xxx
+//
+// options:
+//    "BearerAuth": [{ key: "BearerAuth", scopes: [], ...rest }]
+//    "BearerAuth and BasicAuth": [{ key: "BearerAuth", scopes: [], ...rest }, { key: "BasicAuth", scopes: [], ...rest }]
+//
+// selected: "BearerAuth and BasicAuth"
+
+// LOCAL_STORAGE
+// hash(SLICE_STATE.options) -> "BearerAuth and BasicAuth"
+// BearerAuth                -> { token: xxx }
+// BasicAuth                 -> { username: xxx, password: xxx }
+
+export function createAuth({
+  security,
+  securitySchemes,
+  options: opts,
+}: {
+  security?: SecurityRequirementObject[];
+  securitySchemes?: {
+    [key: string]: SecuritySchemeObject;
+  };
+  options?: ThemeConfig["api"];
+}): AuthState {
+  const storage = createStorage("sessionStorage");
+
+  let data: AuthState["data"] = {};
+  let options: AuthState["options"] = {};
+
+  for (const option of security ?? []) {
+    const id = Object.keys(option).join(" and ");
+    for (const [schemeID, scopes] of Object.entries(option)) {
+      const scheme = securitySchemes?.[schemeID];
+      if (scheme) {
+        if (options[id] === undefined) {
+          options[id] = [];
+        }
+        const dataKeys = getAuthDataKeys(scheme);
+        for (const key of dataKeys) {
+          if (data[schemeID] === undefined) {
+            data[schemeID] = {};
+          }
+
+          let persisted = undefined;
+          try {
+            persisted = JSON.parse(storage.getItem(schemeID) ?? "")[key];
+          } catch {}
+
+          data[schemeID][key] = persisted;
+        }
+        options[id].push({
+          ...scheme,
+          key: schemeID,
+          scopes,
+        });
+      }
+    }
+  }
+
+  let persisted = undefined;
+  try {
+    persisted = storage.getItem(hashArray(Object.keys(options))) ?? undefined;
+  } catch {}
+
+  return {
+    data,
+    options,
+    selected: persisted ?? Object.keys(options)[0],
+  };
+}
+
+export type Scheme = {
+  key: string;
+  scopes: string[];
+} & SecuritySchemeObject;
+
+export interface AuthState {
+  data: {
+    [scheme: string]: {
+      [key: string]: string | undefined;
+    };
+  };
+  options: {
+    [key: string]: Scheme[];
+  };
+  selected?: string;
+}
+
+const initialState: AuthState = {} as any;
+
+export const slice = createSlice({
+  name: "auth",
+  initialState,
+  reducers: {
+    setAuthData: (
+      state,
+      action: PayloadAction<{ scheme: string; key: string; value?: string }>
+    ) => {
+      const { scheme, key, value } = action.payload;
+      state.data[scheme][key] = value;
+    },
+    setSelectedAuth: (state, action: PayloadAction<string>) => {
+      state.selected = action.payload;
+    },
+  },
+});
+
+export const { setAuthData, setSelectedAuth } = slice.actions;
+
+export default slice.reducer;