docusaurus-theme-openapi-docs 1.1.12 → 1.2.0

package/src/theme/ApiDemoPanel/Execute/makeRequest.ts

@@ -0,0 +1,197 @@
+/* ============================================================================
+ * 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 { Body } from "../Body/slice";
+
+function fetchWithtimeout(
+  url: string,
+  options: RequestInit,
+  timeout = 5000
+): any {
+  return Promise.race([
+    fetch(url, options),
+    new Promise((_, reject) =>
+      setTimeout(() => reject(new Error("Request timed out")), timeout)
+    ),
+  ]);
+}
+
+async function loadImage(content: Blob): Promise<string | ArrayBuffer | null> {
+  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: sdk.Request,
+  proxy: string | undefined,
+  _body: Body
+) {
+  const headers = request.toJSON().header;
+
+  let myHeaders = new Headers();
+  if (headers) {
+    headers.forEach((header: any) => {
+      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: RequestInit["body"] = 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: RequestInit = {
+    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: any) => {
+      return response.text();
+    }
+  );
+}
+
+export default makeRequest;

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

@@ -10,16 +10,25 @@ import React from "react";
 import styles from "./styles.module.css";
 
 interface Props {
-  label: string;
+  label?: string;
   type?: string;
+  required?: boolean | undefined;
   children?: React.ReactNode;
 }
 
-function FormItem({ label, type, children }: Props) {
+function FormItem({ label, type, required, children }: Props) {
   return (
     <div className={styles.formItem}>
       <code>{label}</code>
       {type && <span style={{ opacity: 0.6 }}> — {type}</span>}
+      {required && (
+        <span>
+          {" "}
+          <small>
+            <strong className={styles.required}> required</strong>
+          </small>
+        </span>
+      )}
       <div>{children}</div>
     </div>
   );

package/src/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/src/theme/ApiDemoPanel/ParamOptions/index.tsx

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

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

@@ -0,0 +1,71 @@
+/* ============================================================================
+ * 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 { ParameterObject } from "docusaurus-plugin-openapi-docs/src/openapi/types";
+import { ApiItem } from "docusaurus-plugin-openapi-docs/src/types";
+
+import { ThemeConfig } from "../../../types";
+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 }: { item: NonNullable<ApiItem> }) {
+  const response = useTypedSelector((state) => state.response.value);
+  const { siteConfig } = useDocusaurusContext();
+  const themeConfig = siteConfig.themeConfig as ThemeConfig;
+  const options = themeConfig.api;
+  const postman = new sdk.Request(item.postman);
+
+  const params = {
+    path: [] as ParameterObject[],
+    query: [] as ParameterObject[],
+    header: [] as ParameterObject[],
+    cookie: [] as ParameterObject[],
+  };
+
+  item.parameters?.forEach(
+    (param: { in: "path" | "query" | "header" | "cookie" }) => {
+      const paramType = param.in;
+      const paramsArray: ParameterObject[] = params[paramType];
+      paramsArray.push(param as ParameterObject);
+    }
+  );
+
+  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/src/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/src/theme/ApiDemoPanel/Response/index.tsx

@@ -7,8 +7,9 @@
 
 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...
@@ -43,23 +44,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/src/theme/ApiDemoPanel/SecuritySchemes/index.tsx

@@ -19,58 +19,63 @@ function SecuritySchemes(props: any) {
   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/src/theme/ApiDemoPanel/Server/index.tsx

@@ -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/src/theme/ApiDemoPanel/buildPostmanRequest.ts

@@ -261,6 +261,25 @@ function buildPostmanRequest(
       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}`,
+      });
+      continue;
+    }
+
     // Basic Auth
     if (a.type === "http" && a.scheme === "basic") {
       const { username, password } = auth.data[a.key];
@@ -276,8 +295,8 @@ function buildPostmanRequest(
 
     // API Key
     if (a.type === "apiKey" && a.in === "header") {
-      const { apikey } = auth.data[a.key];
-      if (apikey === undefined) {
+      const { apiKey } = auth.data[a.key];
+      if (apiKey === undefined) {
         otherHeaders.push({
           key: a.name,
           value: "<API_KEY_VALUE>",
@@ -286,7 +305,7 @@ function buildPostmanRequest(
       }
       otherHeaders.push({
         key: a.name,
-        value: apikey,
+        value: apiKey,
       });
       continue;
     }

package/src/theme/ApiDemoPanel/index.tsx

@@ -14,13 +14,11 @@ import { ApiItem } from "docusaurus-plugin-openapi-docs/src/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 Request from "./Request";
 import Response from "./Response";
 import SecuritySchemes from "./SecuritySchemes";
 import Server from "./Server";
@@ -95,21 +93,14 @@ function ApiDemoPanel({
     <Provider store={store2}>
       <div className={styles.apiDemoPanelContainer}>
         <MethodEndpoint method={method} path={path} />
-        <SecuritySchemes infoPath={infoPath} />
-        <div className={styles.optionsPanel}>
-          <ParamOptions />
-          <Body
-            jsonRequestBodyExample={item.jsonRequestBodyExample}
-            requestBodyMetadata={item.requestBody}
-          />
-          <Accept />
-        </div>
         <Server />
+        <SecuritySchemes infoPath={infoPath} />
+        <Request item={item} />
+        <Response />
         <Curl
           postman={postman}
           codeSamples={(item as any)["x-code-samples"] ?? []}
         />
-        <Response />
       </div>
     </Provider>
   );

package/src/theme/ApiDemoPanel/persistanceMiddleware.ts

@@ -19,7 +19,7 @@ export function createPersistanceMiddleware(options: ThemeConfig["api"]) {
 
       const state = storeAPI.getState();
 
-      const storage = createStorage(options?.authPersistance);
+      const storage = createStorage("sessionStorage");
 
       if (action.type === setAuthData.type) {
         for (const [key, value] of Object.entries(state.auth.data)) {

package/src/theme/ApiDemoPanel/react-modal.d.ts

@@ -0,0 +1,8 @@
+/* ============================================================================
+ * 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 "react-modal";

package/src/theme/ApiItem/Layout/styles.module.css

@@ -71,6 +71,62 @@
   border-top: unset !important;
 }
 
+:global(.theme-api-markdown .details__demo-panel) {
+  margin-bottom: 1rem;
+  background: var(--openapi-card-background-color);
+  border-radius: var(--openapi-card-border-radius);
+}
+
+:global(.theme-api-markdown .details__demo-panel > summary) {
+  padding-left: 1rem;
+  padding-top: 1rem;
+  cursor: pointer;
+}
+
+:global(.theme-api-markdown .details__demo-panel > div > div > pre) {
+  border-top-left-radius: 0;
+  border-top-right-radius: 0;
+}
+
+:global(.theme-api-markdown .details__demo-panel > summary::marker) {
+  display: none;
+  content: "";
+}
+
+:global(.theme-api-markdown
+    .details__demo-panel
+    > summary::-webkit-details-marker) {
+  display: none;
+  content: "";
+}
+
+:global(.theme-api-markdown .details__demo-panel > pre) {
+  margin-bottom: 0;
+  padding-top: 0;
+}
+
+:global(.theme-api-markdown .details__request-summary) {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+}
+
+:global(.theme-api-markdown .details__request-summary > button) {
+  margin-bottom: 1rem;
+  margin-right: 1rem;
+}
+
+:global(.theme-api-markdown .details__response-summary) {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+}
+
+:global(.theme-api-markdown .details__response-summary > button) {
+  margin-bottom: 1rem;
+  margin-right: 1rem;
+}
+
 :global(.theme-api-markdown code) {
   max-width: 600px;
   max-height: 500px;

package/src/theme/ParamsItem/index.js

@@ -53,7 +53,11 @@ function ParamsItem({
   ));
 
   const renderDefaultValue = guard(
-    schema.items ? schema.items.default : schema.default,
+    schema && schema.items
+      ? schema.items.default
+      : schema
+      ? schema.default
+      : undefined,
     (value) => (
       <div>
         <ReactMarkdown children={`**Default value:** \`${value}\``} />