docusaurus-theme-openapi-docs 1.0.0

package/src/markdown/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.
+ * ========================================================================== */
+
+export type Children = string | undefined | (string | undefined)[];
+
+export type Props = Record<string, any> & { children?: Children };
+
+export function create(tag: string, props: Props): string {
+  const { children, ...rest } = props;
+
+  let propString = "";
+  for (const [key, value] of Object.entries(rest)) {
+    propString += ` ${key}={${JSON.stringify(value)}}`;
+  }
+
+  return `<${tag}${propString}>${render(children)}</${tag}>`;
+}
+
+export function guard<T>(
+  value: T | undefined,
+  cb: (value: T) => Children
+): string {
+  if (value) {
+    const children = cb(value);
+    return render(children);
+  }
+  return "";
+}
+
+export function render(children: Children): string {
+  if (Array.isArray(children)) {
+    return children.filter((c) => c !== undefined).join("");
+  }
+  return children ?? "";
+}

package/src/theme/ApiDemoPanel/Accept/index.tsx

@@ -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 React from "react";
+
+import { useTypedDispatch, useTypedSelector } from "../hooks";
+import FormItem from "./../FormItem";
+import FormSelect from "./../FormSelect";
+import { setAccept } from "./slice";
+
+function Accept() {
+  const value = useTypedSelector((state) => state.accept.value);
+  const options = useTypedSelector((state) => state.accept.options);
+  const dispatch = useTypedDispatch();
+
+  if (options.length <= 1) {
+    return null;
+  }
+
+  return (
+    <FormItem label="Accept">
+      <FormSelect
+        value={value}
+        options={options}
+        onChange={(e) => dispatch(setAccept(e.target.value))}
+      />
+    </FormItem>
+  );
+}
+
+export default Accept;

package/src/theme/ApiDemoPanel/Accept/slice.ts

@@ -0,0 +1,29 @@
+/* ============================================================================
+ * 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";
+
+export interface State {
+  value: string;
+  options: string[];
+}
+
+const initialState: State = {} as any;
+
+export const slice = createSlice({
+  name: "accept",
+  initialState,
+  reducers: {
+    setAccept: (state, action: PayloadAction<string>) => {
+      state.value = action.payload;
+    },
+  },
+});
+
+export const { setAccept } = slice.actions;
+
+export default slice.reducer;

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

@@ -0,0 +1,26 @@
+/* ============================================================================
+ * 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"];
+  }
+
+  // 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/ApiDemoPanel/Authorization/index.tsx

@@ -0,0 +1,211 @@
+/* ============================================================================
+ * 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, { useState } from "react";
+
+import clsx from "clsx";
+
+import FormItem from "../FormItem";
+import FormSelect from "../FormSelect";
+import FormTextInput from "../FormTextInput";
+import { useTypedDispatch, useTypedSelector } from "../hooks";
+import styles from "../styles.module.css";
+import { AuthState, Scheme, setAuthData, setSelectedAuth } from "./slice";
+
+type Props = {
+  mode: "locked" | "unlocked";
+} & JSX.IntrinsicElements["button"];
+
+function LockButton({ mode, children, style, ...rest }: Props) {
+  return (
+    <button
+      className={clsx("button", "button--primary", {
+        "button--outline": mode !== "locked",
+      })}
+      style={{
+        marginLeft: "auto",
+        display: "flex",
+        alignItems: "center",
+        marginBottom: "var(--ifm-spacing-vertical)",
+        ...style,
+      }}
+      {...rest}
+    >
+      <span>{children}</span>
+
+      <svg
+        style={{
+          marginLeft: "12px",
+          width: "18px",
+          height: "18px",
+          fill: "currentColor",
+        }}
+        viewBox="0 0 20 20"
+        id={mode}
+      >
+        {mode === "locked" ? (
+          <path d="M15.8 8H14V5.6C14 2.703 12.665 1 10 1 7.334 1 6 2.703 6 5.6V8H4c-.553 0-1 .646-1 1.199V17c0 .549.428 1.139.951 1.307l1.197.387C5.672 18.861 6.55 19 7.1 19h5.8c.549 0 1.428-.139 1.951-.307l1.196-.387c.524-.167.953-.757.953-1.306V9.199C17 8.646 16.352 8 15.8 8zM12 8H8V5.199C8 3.754 8.797 3 10 3c1.203 0 2 .754 2 2.199V8z"></path>
+        ) : (
+          <path d="M15.8 8H14V5.6C14 2.703 12.665 1 10 1 7.334 1 6 2.703 6 5.6V6h2v-.801C8 3.754 8.797 3 10 3c1.203 0 2 .754 2 2.199V8H4c-.553 0-1 .646-1 1.199V17c0 .549.428 1.139.951 1.307l1.197.387C5.672 18.861 6.55 19 7.1 19h5.8c.549 0 1.428-.139 1.951-.307l1.196-.387c.524-.167.953-.757.953-1.306V9.199C17 8.646 16.352 8 15.8 8z"></path>
+        )}
+      </svg>
+    </button>
+  );
+}
+
+function validateData(selectedAuth: Scheme[], data: AuthState["data"]) {
+  for (const scheme of selectedAuth) {
+    if (data[scheme.key] === undefined) {
+      return false;
+    }
+    const hasMissingKeys = Object.values(data[scheme.key]).includes(undefined);
+    if (hasMissingKeys) {
+      return false;
+    }
+  }
+  return true;
+}
+
+function Authorization() {
+  const [editing, setEditing] = useState(false);
+
+  const data = useTypedSelector((state) => state.auth.data);
+  const options = useTypedSelector((state) => state.auth.options);
+  const selected = useTypedSelector((state) => state.auth.selected);
+
+  const dispatch = useTypedDispatch();
+
+  if (selected === undefined) {
+    return null;
+  }
+
+  const selectedAuth = options[selected];
+
+  const authenticated = validateData(selectedAuth, data);
+
+  const optionKeys = Object.keys(options);
+
+  if (editing) {
+    return (
+      <div className={styles.optionsPanel}>
+        {optionKeys.length > 1 && (
+          <FormItem label="Security Scheme">
+            <FormSelect
+              options={optionKeys}
+              value={selected}
+              onChange={(e) => {
+                dispatch(setSelectedAuth(e.target.value));
+              }}
+            />
+          </FormItem>
+        )}
+        {selectedAuth.map((a) => {
+          if (a.type === "http" && a.scheme === "bearer") {
+            return (
+              <FormItem label="Bearer Token" key={selected + "-bearer"}>
+                <FormTextInput
+                  placeholder="Bearer Token"
+                  value={data[a.key].token ?? ""}
+                  onChange={(e) => {
+                    const value = e.target.value.trim();
+                    dispatch(
+                      setAuthData({
+                        scheme: a.key,
+                        key: "token",
+                        value: value ? value : undefined,
+                      })
+                    );
+                  }}
+                />
+              </FormItem>
+            );
+          }
+
+          if (a.type === "http" && a.scheme === "basic") {
+            return (
+              <React.Fragment key={selected + "-basic"}>
+                <FormItem label="Username">
+                  <FormTextInput
+                    placeholder="Username"
+                    value={data[a.key].username ?? ""}
+                    onChange={(e) => {
+                      const value = e.target.value.trim();
+                      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) => {
+                      const value = e.target.value.trim();
+                      dispatch(
+                        setAuthData({
+                          scheme: a.key,
+                          key: "password",
+                          value: value ? value : undefined,
+                        })
+                      );
+                    }}
+                  />
+                </FormItem>
+              </React.Fragment>
+            );
+          }
+
+          return null;
+        })}
+        <LockButton
+          mode="unlocked"
+          style={{
+            marginTop: "var(--ifm-spacing-vertical)",
+            marginBottom: 0,
+          }}
+          onClick={() => {
+            setEditing(false);
+          }}
+        >
+          Save
+        </LockButton>
+      </div>
+    );
+  }
+
+  if (authenticated) {
+    return (
+      <LockButton
+        mode="locked"
+        onClick={() => {
+          setEditing(true);
+        }}
+      >
+        Authorized
+      </LockButton>
+    );
+  }
+
+  return (
+    <LockButton
+      mode="unlocked"
+      onClick={() => {
+        setEditing(true);
+      }}
+    >
+      Authorize
+    </LockButton>
+  );
+}
+
+export default Authorization;

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

@@ -0,0 +1,145 @@
+/* ============================================================================
+ * 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 {
+  SecurityRequirementObject,
+  SecuritySchemeObject,
+} from "docusaurus-plugin-openapi-docs/src/openapi/types";
+
+import { ThemeConfig } from "../../../types";
+import { createStorage, hashArray } from "../storage-utils";
+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(opts?.authPersistance);
+
+  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;

package/src/theme/ApiDemoPanel/Body/index.tsx

@@ -0,0 +1,218 @@
+/* ============================================================================
+ * 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 { RequestBodyObject } from "docusaurus-plugin-openapi-docs/src/openapi/types";
+
+import ContentType from "../ContentType";
+import FormSelect from "../FormSelect";
+import { useTypedDispatch, useTypedSelector } from "../hooks";
+import FormFileUpload from "./../FormFileUpload";
+import FormItem from "./../FormItem";
+import FormTextInput from "./../FormTextInput";
+import VSCode from "./../VSCode";
+import {
+  clearFormBodyKey,
+  clearRawBody,
+  setFileFormBody,
+  setFileRawBody,
+  setStringFormBody,
+  setStringRawBody,
+} from "./slice";
+
+interface Props {
+  jsonRequestBodyExample: string;
+  requestBodyMetadata?: RequestBodyObject;
+}
+
+function BodyWrap({ requestBodyMetadata, jsonRequestBodyExample }: Props) {
+  const contentType = useTypedSelector((state) => state.contentType.value);
+
+  // NOTE: We used to check if body was required, but opted to always show the request body
+  // to reduce confusion, see: https://github.com/cloud-annotations/docusaurus-openapi/issues/145
+
+  // No body
+  if (contentType === undefined) {
+    return null;
+  }
+
+  return (
+    <>
+      <ContentType />
+      <Body
+        requestBodyMetadata={requestBodyMetadata}
+        jsonRequestBodyExample={jsonRequestBodyExample}
+      />
+    </>
+  );
+}
+
+function Body({ requestBodyMetadata, jsonRequestBodyExample }: Props) {
+  const contentType = useTypedSelector((state) => state.contentType.value);
+
+  const dispatch = useTypedDispatch();
+
+  // Lot's of possible content-types:
+  // - application/json
+  // - application/xml
+  // - text/plain
+  // - text/css
+  // - text/html
+  // - text/javascript
+  // - application/javascript
+  // - multipart/form-data
+  // - application/x-www-form-urlencoded
+  // - image/svg+xml;charset=US-ASCII
+
+  // Show editor:
+  // - application/json
+  // - application/xml
+  // - */*
+
+  // Show form:
+  // - multipart/form-data
+  // - application/x-www-form-urlencoded
+
+  const schema = requestBodyMetadata?.content?.[contentType]?.schema;
+
+  if (schema?.format === "binary") {
+    return (
+      <FormItem label="Body">
+        <FormFileUpload
+          placeholder={schema.description || "Body"}
+          onChange={(file) => {
+            if (file === undefined) {
+              dispatch(clearRawBody());
+              return;
+            }
+            dispatch(
+              setFileRawBody({
+                src: `/path/to/${file.name}`,
+                content: file,
+              })
+            );
+          }}
+        />
+      </FormItem>
+    );
+  }
+
+  if (
+    (contentType === "multipart/form-data" ||
+      contentType === "application/x-www-form-urlencoded") &&
+    schema?.type === "object"
+  ) {
+    return (
+      <FormItem label="Body">
+        <div
+          style={{
+            marginTop: "calc(var(--ifm-pre-padding) / 2)",
+            borderRadius: "4px",
+            padding: "var(--ifm-pre-padding)",
+            border: "1px solid var(--openapi-monaco-border-color)",
+          }}
+        >
+          {Object.entries(schema.properties ?? {}).map(([key, val]: any) => {
+            if (val.format === "binary") {
+              return (
+                <FormItem key={key} label={key}>
+                  <FormFileUpload
+                    placeholder={val.description || key}
+                    onChange={(file) => {
+                      if (file === undefined) {
+                        dispatch(clearFormBodyKey(key));
+                        return;
+                      }
+                      dispatch(
+                        setFileFormBody({
+                          key: key,
+                          value: {
+                            src: `/path/to/${file.name}`,
+                            content: file,
+                          },
+                        })
+                      );
+                    }}
+                  />
+                </FormItem>
+              );
+            }
+
+            if (val.enum) {
+              return (
+                <FormItem key={key} label={key}>
+                  <FormSelect
+                    options={["---", ...val.enum]}
+                    onChange={(e) => {
+                      const val = e.target.value;
+                      if (val === "---") {
+                        dispatch(clearFormBodyKey(key));
+                      } else {
+                        dispatch(
+                          setStringFormBody({
+                            key: key,
+                            value: val,
+                          })
+                        );
+                      }
+                    }}
+                  />
+                </FormItem>
+              );
+            }
+            // TODO: support all the other types.
+            return (
+              <FormItem key={key} label={key}>
+                <FormTextInput
+                  placeholder={val.description || key}
+                  onChange={(e) => {
+                    dispatch(
+                      setStringFormBody({ key: key, value: e.target.value })
+                    );
+                  }}
+                />
+              </FormItem>
+            );
+          })}
+        </div>
+      </FormItem>
+    );
+  }
+
+  let language = "plaintext";
+  let exampleBodyString = ""; //"body content";
+
+  if (contentType === "application/json") {
+    if (jsonRequestBodyExample) {
+      exampleBodyString = JSON.stringify(jsonRequestBodyExample, null, 2);
+    }
+    language = "json";
+  }
+
+  if (contentType === "application/xml") {
+    language = "xml";
+  }
+
+  return (
+    <FormItem label="Body">
+      <VSCode
+        value={exampleBodyString}
+        language={language}
+        onChange={(value) => {
+          if (value.trim() === "") {
+            dispatch(clearRawBody());
+            return;
+          }
+          dispatch(setStringRawBody(value));
+        }}
+      />
+    </FormItem>
+  );
+}
+
+export default BodyWrap;