docusaurus-theme-openapi-docs 1.1.12 → 1.2.0

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

@@ -0,0 +1,170 @@
+/* ============================================================================
+ * 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 Modal from "react-modal";
+import { useTypedDispatch, useTypedSelector } from "../hooks";
+import { setResponse } from "../Response/slice";
+import buildPostmanRequest from "./../buildPostmanRequest";
+import makeRequest from "./makeRequest";
+
+function validateRequest(params) {
+  for (let paramList of Object.values(params)) {
+    for (let param of paramList) {
+      if (param.required && !param.value) {
+        return false;
+      }
+    }
+  }
+
+  return true;
+}
+
+function Execute({ postman, proxy }) {
+  const pathParams = useTypedSelector((state) => state.params.path);
+  const queryParams = useTypedSelector((state) => state.params.query);
+  const cookieParams = useTypedSelector((state) => state.params.cookie);
+  const headerParams = useTypedSelector((state) => state.params.header);
+  const contentType = useTypedSelector((state) => state.contentType.value);
+  const body = useTypedSelector((state) => state.body);
+  const accept = useTypedSelector((state) => state.accept.value);
+  const server = useTypedSelector((state) => state.server.value);
+  const params = useTypedSelector((state) => state.params);
+  const auth = useTypedSelector((state) => state.auth);
+  const isValidRequest = validateRequest(params);
+  const dispatch = useTypedDispatch();
+  const postmanRequest = buildPostmanRequest(postman, {
+    queryParams,
+    pathParams,
+    cookieParams,
+    contentType,
+    accept,
+    headerParams,
+    body,
+    server,
+    auth,
+  });
+
+  const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+  function openModal() {
+    setIsOpen(true);
+  }
+
+  function closeModal() {
+    setIsOpen(false);
+  }
+
+  function acceptAgreement() {
+    setIsOpen(false);
+    setAgreementAccepted(true);
+    sessionStorage.setItem("agreement-ack", "true");
+  }
+
+  const [modalIsOpen, setIsOpen] = React.useState(false); // Set the following as default value to persist to session and enable modal
+  // sessionStorage.getItem("agreement-ack") === "true"
+
+  const [agreementAccepted, setAgreementAccepted] = React.useState(true);
+  const customStyles = {
+    overlay: {
+      backdropFilter: "blur(10px)",
+      backgroundColor: "transparent",
+    },
+    content: {
+      top: "50%",
+      left: "50%",
+      right: "auto",
+      bottom: "auto",
+      marginRight: "-50%",
+      border: "none",
+      padding: "none",
+      borderRadius: "var(--openapi-card-border-radius)",
+      background: "var(--ifm-card-background-color)",
+      transform: "translate(-50%, -50%)",
+      maxWidth: "550px",
+    },
+  };
+
+  if (agreementAccepted) {
+    return (
+      <button
+        className="button button--sm button--secondary"
+        disabled={!isValidRequest}
+        onClick={async () => {
+          dispatch(setResponse("Fetching..."));
+
+          try {
+            await delay(1200);
+            const res = await makeRequest(postmanRequest, proxy, body);
+            dispatch(setResponse(res));
+          } catch (e) {
+            console.log(e);
+            dispatch(setResponse("Connection failed"));
+          }
+        }}
+      >
+        Send API Request
+      </button>
+    );
+  } else {
+    return (
+      <React.Fragment>
+        <button
+          className="button button--sm button--secondary"
+          onClick={openModal}
+        >
+          Send API Request
+        </button>
+        <Modal
+          isOpen={modalIsOpen}
+          onRequestClose={closeModal}
+          style={customStyles}
+          contentLabel="Terms of Use"
+        >
+          <form>
+            <div className="card">
+              <div className="card__header">
+                <h2>Terms of Use</h2>
+                <hr></hr>
+              </div>
+              <div className="card__body">
+                <p>
+                  By accepting this agreement the end user acknowledges the
+                  risks of performing authenticated and non-authenticated API
+                  requests from the browser.
+                </p>
+                <p>
+                  The end user also accepts the responsibility of safeguarding
+                  API credentials and any potentially sensitive data returned by
+                  the API.
+                </p>
+                <br></br>
+              </div>
+              <div className="card__footer">
+                <div className="button-group button-group--block">
+                  <button
+                    className="button button--sm button--outline button--success"
+                    onClick={acceptAgreement}
+                  >
+                    AGREE
+                  </button>
+                  <button
+                    className="button button--sm button--outline button--danger"
+                    onClick={closeModal}
+                  >
+                    DISAGREE
+                  </button>
+                </div>
+              </div>
+            </div>
+          </form>
+        </Modal>
+      </React.Fragment>
+    );
+  }
+}
+
+export default Execute;

package/lib-next/theme/ApiDemoPanel/Execute/makeRequest.js

@@ -0,0 +1,190 @@
+/* ============================================================================
+ * 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.
+ * ========================================================================== */
+function fetchWithtimeout(url, options, timeout = 5000) {
+  return Promise.race([
+    fetch(url, options),
+    new Promise((_, reject) =>
+      setTimeout(() => reject(new Error("Request timed out")), timeout)
+    ),
+  ]);
+}
+
+async function loadImage(content) {
+  return new Promise((accept, reject) => {
+    const reader = new FileReader();
+
+    reader.onabort = () => {
+      console.log("file reading was aborted");
+      reject();
+    };
+
+    reader.onerror = () => {
+      console.log("file reading has failed");
+      reject();
+    };
+
+    reader.onload = () => {
+      // Do whatever you want with the file contents
+      const binaryStr = reader.result;
+      accept(binaryStr);
+    };
+
+    reader.readAsArrayBuffer(content);
+  });
+}
+
+async function makeRequest(request, proxy, _body) {
+  const headers = request.toJSON().header;
+  let myHeaders = new Headers();
+
+  if (headers) {
+    headers.forEach((header) => {
+      if (header.key && header.value) {
+        myHeaders.append(header.key, header.value);
+      }
+    });
+  } // The following code handles multiple files in the same formdata param.
+  // It removes the form data params where the src property is an array of filepath strings
+  // Splits that array into different form data params with src set as a single filepath string
+  // TODO:
+  // if (request.body && request.body.mode === 'formdata') {
+  //   let formdata = request.body.formdata,
+  //     formdataArray = [];
+  //   formdata.members.forEach((param) => {
+  //     let key = param.key,
+  //       type = param.type,
+  //       disabled = param.disabled,
+  //       contentType = param.contentType;
+  //     // check if type is file or text
+  //     if (type === 'file') {
+  //       // if src is not of type string we check for array(multiple files)
+  //       if (typeof param.src !== 'string') {
+  //         // if src is an array(not empty), iterate over it and add files as separate form fields
+  //         if (Array.isArray(param.src) && param.src.length) {
+  //           param.src.forEach((filePath) => {
+  //             addFormParam(
+  //               formdataArray,
+  //               key,
+  //               param.type,
+  //               filePath,
+  //               disabled,
+  //               contentType
+  //             );
+  //           });
+  //         }
+  //         // if src is not an array or string, or is an empty array, add a placeholder for file path(no files case)
+  //         else {
+  //           addFormParam(
+  //             formdataArray,
+  //             key,
+  //             param.type,
+  //             '/path/to/file',
+  //             disabled,
+  //             contentType
+  //           );
+  //         }
+  //       }
+  //       // if src is string, directly add the param with src as filepath
+  //       else {
+  //         addFormParam(
+  //           formdataArray,
+  //           key,
+  //           param.type,
+  //           param.src,
+  //           disabled,
+  //           contentType
+  //         );
+  //       }
+  //     }
+  //     // if type is text, directly add it to formdata array
+  //     else {
+  //       addFormParam(
+  //         formdataArray,
+  //         key,
+  //         param.type,
+  //         param.value,
+  //         disabled,
+  //         contentType
+  //       );
+  //     }
+  //   });
+  //   request.body.update({
+  //     mode: 'formdata',
+  //     formdata: formdataArray,
+  //   });
+  // }
+
+  const body = request.body?.toJSON();
+  let myBody = undefined;
+
+  if (body !== undefined && Object.keys(body).length > 0) {
+    switch (body.mode) {
+      case "urlencoded": {
+        myBody = new URLSearchParams();
+
+        if (Array.isArray(body.urlencoded)) {
+          for (const data of body.urlencoded) {
+            if (data.key && data.value) {
+              myBody.append(data.key, data.value);
+            }
+          }
+        }
+
+        break;
+      }
+
+      case "raw": {
+        myBody = (body.raw ?? "").toString();
+        break;
+      }
+
+      case "formdata": {
+        myBody = new FormData();
+
+        if (Array.isArray(body.formdata)) {
+          for (const data of body.formdata) {
+            if (data.key && data.value) {
+              myBody.append(data.key, data.value);
+            }
+          }
+        }
+
+        break;
+      }
+
+      case "file": {
+        if (_body.type === "raw" && _body.content?.type === "file") {
+          myBody = await loadImage(_body.content.value.content);
+        }
+
+        break;
+      }
+
+      default:
+        break;
+    }
+  }
+
+  const requestOptions = {
+    method: request.method,
+    headers: myHeaders,
+    body: myBody,
+  };
+  let finalUrl = request.url.toString();
+
+  if (proxy) {
+    // Ensure the proxy ends with a slash.
+    let normalizedProxy = proxy.replace(/\/$/, "") + "/";
+    finalUrl = normalizedProxy + request.url.toString();
+  }
+
+  return await fetchWithtimeout(finalUrl, requestOptions).then((response) => {
+    return response.text();
+  });
+}
+
+export default makeRequest;

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

@@ -7,7 +7,7 @@
 import React from "react";
 import styles from "./styles.module.css";
 
-function FormItem({ label, type, children }) {
+function FormItem({ label, type, required, children }) {
   return (
     <div className={styles.formItem}>
       <code>{label}</code>
@@ -21,6 +21,14 @@ function FormItem({ label, type, children }) {
           — {type}
         </span>
       )}
+      {required && (
+        <span>
+          {" "}
+          <small>
+            <strong className={styles.required}> required</strong>
+          </small>
+        </span>
+      )}
       <div>{children}</div>
     </div>
   );

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

@@ -5,3 +5,8 @@
 .formItem:first-child {
   margin-top: 0;
 }
+
+.required {
+  font-size: var(--ifm-code-font-size);
+  color: var(--openapi-required);
+}

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

@@ -37,7 +37,7 @@ function ParamOption({ param }) {
 
 function ParamOptionWrapper({ param }) {
   return (
-    <FormItem label={param.name} type={param.in}>
+    <FormItem label={param.name} type={param.in} required={param.required}>
       <ParamOption param={param} />
     </FormItem>
   );

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

@@ -0,0 +1,60 @@
+/* ============================================================================
+ * 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";
+import sdk from "@paloaltonetworks/postman-collection";
+import Accept from "../Accept";
+import Authorization from "../Authorization";
+import Body from "../Body";
+import Execute from "../Execute";
+import { useTypedSelector } from "../hooks";
+import ParamOptions from "../ParamOptions";
+import styles from "./styles.module.css";
+
+function Request({ item }) {
+  const response = useTypedSelector((state) => state.response.value);
+  const { siteConfig } = useDocusaurusContext();
+  const themeConfig = siteConfig.themeConfig;
+  const options = themeConfig.api;
+  const postman = new sdk.Request(item.postman);
+  const params = {
+    path: [],
+    query: [],
+    header: [],
+    cookie: [],
+  };
+  item.parameters?.forEach((param) => {
+    const paramType = param.in;
+    const paramsArray = params[paramType];
+    paramsArray.push(param);
+  });
+  return (
+    <div>
+      <details className={`details__demo-panel`} open={response ? false : true}>
+        <summary>
+          <div className={`details__request-summary`}>
+            <h4>Request</h4>
+            {item.servers && (
+              <Execute postman={postman} proxy={options?.proxy} />
+            )}
+          </div>
+        </summary>
+        <div className={styles.optionsPanel}>
+          <Authorization />
+          <ParamOptions />
+          <Body
+            jsonRequestBodyExample={item.jsonRequestBodyExample}
+            requestBodyMetadata={item.requestBody}
+          />
+          <Accept />
+        </div>
+      </details>
+    </div>
+  );
+}
+
+export default Request;

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

@@ -0,0 +1,17 @@
+.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;
+}

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

@@ -5,8 +5,8 @@
  * LICENSE file in the root directory of this source tree.
  * ========================================================================== */
 import React from "react";
+import CodeBlock from "@theme/CodeBlock";
 import { useTypedDispatch, useTypedSelector } from "../hooks";
-import FloatingButton from "./../FloatingButton";
 import { clearResponse } from "./slice"; // TODO: We probably shouldn't attempt to format XML...
 
 function formatXml(xml) {
@@ -42,23 +42,28 @@ function Response() {
   try {
     prettyResponse = JSON.stringify(JSON.parse(response), null, 2);
   } catch {
-    if (response.startsWith("<?xml ")) {
+    if (response.startsWith("<")) {
       prettyResponse = formatXml(response);
     }
   }
 
   return (
-    <FloatingButton onClick={() => dispatch(clearResponse())} label="Clear">
-      <pre
-        style={{
-          background: "var(--openapi-card-background-color)",
-          borderRadius: "var(--openapi-card-border-radius)",
-          paddingRight: "60px",
-        }}
-      >
-        <code>{prettyResponse || "No Response"}</code>
-      </pre>
-    </FloatingButton>
+    <details className={`details__demo-panel`} open={true}>
+      <summary>
+        <div className={`details__response-summary`}>
+          <h4>Response</h4>
+          <button
+            className="button button--sm button--secondary"
+            onClick={() => dispatch(clearResponse())}
+          >
+            Clear
+          </button>
+        </div>
+      </summary>
+      <CodeBlock language={response.startsWith("<") ? `xml` : `json`}>
+        {prettyResponse || "No Response"}
+      </CodeBlock>
+    </details>
   );
 }
 

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

@@ -15,60 +15,62 @@ function SecuritySchemes(props) {
   if (selected === undefined) return null;
   const selectedAuth = options[selected];
   return (
-    <div
-      style={{
-        marginBottom: "var(--ifm-table-cell-padding)",
-      }}
-    >
+    <details className={`details__demo-panel`} open={false}>
+      <summary className={`details__request-summary`}>
+        <h4>Authorization</h4>
+      </summary>
       {selectedAuth.map((auth) => {
         const isApiKey = auth.type === "apiKey";
         const isBearer = auth.type === "http" && auth.key === "Bearer";
-        const isClientCredentials =
-          auth.type === "oauth2" && auth.key === "ClientCredentials";
+        const isOauth2 = auth.type === "oauth2";
 
         if (isApiKey || isBearer) {
           return (
-            <React.Fragment key={selected}>
-              <b>
-                Authorization: <Link to={infoAuthPath}>{auth.key}</Link>
-              </b>
+            <React.Fragment key={auth.key}>
               <pre
                 style={{
                   display: "flex",
                   flexDirection: "column",
                   background: "var(--openapi-card-background-color)",
-                  borderRadius: "var(--openapi-card-border-radius)",
                 }}
               >
-                <span>name: {auth.name}</span>
-                <span>in: {auth.in}</span>
                 <span>type: {auth.type}</span>
+                <span>
+                  name: <Link to={infoAuthPath}>{auth.name}</Link>
+                </span>
+                <span>in: {auth.in}</span>
               </pre>
             </React.Fragment>
           );
         }
 
-        if (isClientCredentials) {
+        if (isOauth2) {
           return (
             <React.Fragment key={selected}>
-              <b>Authorization: {auth.key}</b>
               <pre
                 style={{
                   display: "flex",
                   flexDirection: "column",
                   background: "var(--openapi-card-background-color)",
-                  borderRadius: "var(--openapi-card-border-radius)",
                 }}
               >
-                <span>type: {auth.type}</span>
+                <span>
+                  type: <Link to={infoAuthPath}>{auth.type}</Link>
+                </span>
+                {Object.keys(auth.flows).map((flow) => {
+                  return <span key={flow}>flow: {flow}</span>;
+                })}
+                <span>
+                  scopes: <code>{auth.scopes.toString()}</code>
+                </span>
               </pre>
             </React.Fragment>
           );
         }
 
-        return null;
+        return undefined;
       })}
-    </div>
+    </details>
   );
 }
 

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

@@ -71,6 +71,7 @@ function Server() {
           options={options.map((s) => s.url)}
           onChange={(e) => dispatch(setServer(e.target.value))}
         />
+        <small>{value?.description}</small>
       </FormItem>
       {value?.variables &&
         Object.keys(value.variables).map((key) => {

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

@@ -258,6 +258,28 @@ function buildPostmanRequest(
         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}`,
@@ -280,9 +302,9 @@ function buildPostmanRequest(
     } // API Key
 
     if (a.type === "apiKey" && a.in === "header") {
-      const { apikey } = auth.data[a.key];
+      const { apiKey } = auth.data[a.key];
 
-      if (apikey === undefined) {
+      if (apiKey === undefined) {
         otherHeaders.push({
           key: a.name,
           value: "<API_KEY_VALUE>",
@@ -292,7 +314,7 @@ function buildPostmanRequest(
 
       otherHeaders.push({
         key: a.name,
-        value: apikey,
+        value: apiKey,
       });
       continue;
     }