docusaurus-theme-openapi-docs 4.5.0 → 4.6.0

package/src/theme/ApiExplorer/Body/FormBodyItem/index.tsx

@@ -0,0 +1,120 @@
+/* ============================================================================
+ * 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 FormFileUpload from "@theme/ApiExplorer/FormFileUpload";
+import FormSelect from "@theme/ApiExplorer/FormSelect";
+import FormTextInput from "@theme/ApiExplorer/FormTextInput";
+import LiveApp from "@theme/ApiExplorer/LiveEditor";
+import { useTypedDispatch } from "@theme/ApiItem/hooks";
+import { SchemaObject } from "docusaurus-plugin-openapi-docs/src/openapi/types";
+import { clearFormBodyKey, setFileFormBody, setStringFormBody } from "../slice";
+import FileArrayFormBodyItem from "../FileArrayFormBodyItem";
+
+interface FormBodyItemProps {
+  schemaObject: SchemaObject;
+  id: string;
+  schema: SchemaObject;
+}
+
+export default function FormBodyItem({
+  schemaObject,
+  id,
+  schema,
+}: FormBodyItemProps): React.JSX.Element {
+  const dispatch = useTypedDispatch();
+
+  if (
+    schemaObject.type === "array" &&
+    schemaObject.items?.format === "binary"
+  ) {
+    return (
+      <FileArrayFormBodyItem id={id} description={schemaObject.description} />
+    );
+  }
+
+  if (schemaObject.format === "binary") {
+    return (
+      <FormFileUpload
+        placeholder={schemaObject.description || id}
+        onChange={(file: any) => {
+          if (file === undefined) {
+            dispatch(clearFormBodyKey(id));
+            return;
+          }
+          dispatch(
+            setFileFormBody({
+              key: id,
+              value: {
+                src: `/path/to/${file.name}`,
+                content: file,
+              },
+            })
+          );
+        }}
+      />
+    );
+  }
+
+  if (
+    schemaObject.type === "object" &&
+    (schemaObject.example || schemaObject.examples)
+  ) {
+    const objectExample = JSON.stringify(
+      schemaObject.example ?? schemaObject.examples[0],
+      null,
+      2
+    );
+
+    return (
+      <LiveApp
+        action={(code: string) =>
+          dispatch(setStringFormBody({ key: id, value: code }))
+        }
+      >
+        {objectExample}
+      </LiveApp>
+    );
+  }
+
+  if (
+    schemaObject.enum &&
+    schemaObject.enum.every((value) => typeof value === "string")
+  ) {
+    return (
+      <FormSelect
+        options={["---", ...schemaObject.enum]}
+        onChange={(e: React.ChangeEvent<HTMLSelectElement>) => {
+          const val = e.target.value;
+          if (val === "---") {
+            dispatch(clearFormBodyKey(id));
+          } else {
+            dispatch(
+              setStringFormBody({
+                key: id,
+                value: val,
+              })
+            );
+          }
+        }}
+      />
+    );
+  }
+  // TODO: support all the other types.
+  return (
+    <FormTextInput
+      paramName={id}
+      isRequired={
+        Array.isArray(schema.required) && schema.required.includes(id)
+      }
+      placeholder={schemaObject.description || id}
+      onChange={(e: React.ChangeEvent<HTMLInputElement>) => {
+        dispatch(setStringFormBody({ key: id, value: e.target.value }));
+      }}
+    />
+  );
+}

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

@@ -7,26 +7,22 @@
 
 import React from "react";
 
+import { translate } from "@docusaurus/Translate";
+
 import json2xml from "@theme/ApiExplorer/Body/json2xml";
 import FormFileUpload from "@theme/ApiExplorer/FormFileUpload";
 import FormItem from "@theme/ApiExplorer/FormItem";
-import FormSelect from "@theme/ApiExplorer/FormSelect";
-import FormTextInput from "@theme/ApiExplorer/FormTextInput";
 import LiveApp from "@theme/ApiExplorer/LiveEditor";
 import { useTypedDispatch, useTypedSelector } from "@theme/ApiItem/hooks";
 import Markdown from "@theme/Markdown";
 import SchemaTabs from "@theme/SchemaTabs";
 import TabItem from "@theme/TabItem";
+import { OPENAPI_BODY, OPENAPI_REQUEST } from "@theme/translationIds";
 import { RequestBodyObject } from "docusaurus-plugin-openapi-docs/src/openapi/types";
 import format from "xml-formatter";
 
-import {
-  clearFormBodyKey,
-  clearRawBody,
-  setFileFormBody,
-  setFileRawBody,
-  setStringFormBody,
-} from "./slice";
+import { clearRawBody, setFileRawBody, setStringRawBody } from "./slice";
+import FormBodyItem from "./FormBodyItem";
 
 export interface Props {
   jsonRequestBodyExample: string;
@@ -93,12 +89,17 @@ function Body({
   const schema = requestBodyMetadata?.content?.[contentType]?.schema;
   const example = requestBodyMetadata?.content?.[contentType]?.example;
   const examples = requestBodyMetadata?.content?.[contentType]?.examples;
+  // OpenAPI 3.1 / JSON Schema: schema.examples is an array of example values
+  const schemaExamples = schema?.examples as any[] | undefined;
 
   if (schema?.format === "binary") {
     return (
       <FormItem>
         <FormFileUpload
-          placeholder={schema.description || "Body"}
+          placeholder={
+            schema.description ||
+            translate({ id: OPENAPI_REQUEST.BODY_TITLE, message: "Body" })
+          }
           onChange={(file: any) => {
             if (file === undefined) {
               dispatch(clearRawBody());
@@ -122,96 +123,23 @@ function Body({
   ) {
     return (
       <FormItem className="openapi-explorer__form-item-body-container">
-        <div>
-          {Object.entries(schema.properties ?? {}).map(([key, val]: any) => {
-            if (val.format === "binary") {
-              return (
-                <FormItem
-                  key={key}
-                  label={key}
-                  required={
-                    Array.isArray(schema.required) &&
-                    schema.required.includes(key)
-                  }
-                >
-                  <FormFileUpload
-                    placeholder={val.description || key}
-                    onChange={(file: any) => {
-                      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}
-                  required={
-                    Array.isArray(schema.required) &&
-                    schema.required.includes(key)
-                  }
-                >
-                  <FormSelect
-                    options={["---", ...val.enum]}
-                    onChange={(e: React.ChangeEvent<HTMLInputElement>) => {
-                      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}
-                required={
-                  Array.isArray(schema.required) &&
-                  schema.required.includes(key)
-                }
-              >
-                <FormTextInput
-                  paramName={key}
-                  isRequired={
-                    Array.isArray(schema.required) &&
-                    schema.required.includes(key)
-                  }
-                  placeholder={val.description || key}
-                  onChange={(e: React.ChangeEvent<HTMLInputElement>) => {
-                    dispatch(
-                      setStringFormBody({ key: key, value: e.target.value })
-                    );
-                  }}
-                />
-              </FormItem>
-            );
-          })}
-        </div>
+        {Object.entries(schema.properties ?? {}).map(([key, val]: any) => {
+          return (
+            <FormItem
+              key={key}
+              label={key}
+              required={
+                Array.isArray(schema.required) && schema.required.includes(key)
+              }
+            >
+              <FormBodyItem
+                schemaObject={val}
+                id={key}
+                schema={schema}
+              ></FormBodyItem>
+            </FormItem>
+          );
+        })}
       </FormItem>
     );
   }
@@ -248,6 +176,17 @@ function Body({
         });
       }
     }
+    // OpenAPI 3.1: schema.examples is an array of example values
+    if (schemaExamples && Array.isArray(schemaExamples)) {
+      schemaExamples.forEach((schemaExample, index) => {
+        const body = JSON.stringify(schemaExample, null, 2);
+        examplesBodies.push({
+          label: `Example ${index + 1}`,
+          body,
+          summary: undefined,
+        });
+      });
+    }
     language = "json";
   }
 
@@ -293,6 +232,26 @@ function Body({
         });
       }
     }
+    // OpenAPI 3.1: schema.examples is an array of example values
+    if (schemaExamples && Array.isArray(schemaExamples)) {
+      schemaExamples.forEach((schemaExample, index) => {
+        let formattedXmlBody;
+        try {
+          formattedXmlBody = format(json2xml(schemaExample, ""), {
+            indentation: "  ",
+            lineSeparator: "\n",
+            collapseContent: true,
+          });
+        } catch {
+          formattedXmlBody = json2xml(schemaExample);
+        }
+        examplesBodies.push({
+          label: `Example ${index + 1}`,
+          body: formattedXmlBody,
+          summary: undefined,
+        });
+      });
+    }
     language = "xml";
   }
 
@@ -302,11 +261,18 @@ function Body({
         <SchemaTabs className="openapi-tabs__schema" lazy>
           {/* @ts-ignore */}
           <TabItem
-            label="Example (from schema)"
+            label={translate({
+              id: OPENAPI_BODY.EXAMPLE_FROM_SCHEMA,
+              message: "Example (from schema)",
+            })}
             value="Example (from schema)"
             default
           >
-            <LiveApp action={dispatch} language={language} required={required}>
+            <LiveApp
+              action={(code: string) => dispatch(setStringRawBody(code))}
+              language={language}
+              required={required}
+            >
               {defaultBody}
             </LiveApp>
           </TabItem>
@@ -315,7 +281,7 @@ function Body({
             {example.summary && <Markdown>{example.summary}</Markdown>}
             {exampleBody && (
               <LiveApp
-                action={dispatch}
+                action={(code: string) => dispatch(setStringRawBody(code))}
                 language={language}
                 required={required}
               >
@@ -334,11 +300,18 @@ function Body({
         <SchemaTabs className="openapi-tabs__schema" lazy>
           {/* @ts-ignore */}
           <TabItem
-            label="Example (from schema)"
+            label={translate({
+              id: OPENAPI_BODY.EXAMPLE_FROM_SCHEMA,
+              message: "Example (from schema)",
+            })}
             value="Example (from schema)"
             default
           >
-            <LiveApp action={dispatch} language={language} required={required}>
+            <LiveApp
+              action={(code: string) => dispatch(setStringRawBody(code))}
+              language={language}
+              required={required}
+            >
               {defaultBody}
             </LiveApp>
           </TabItem>
@@ -352,7 +325,10 @@ function Body({
               >
                 {example.summary && <Markdown>{example.summary}</Markdown>}
                 {example.body && (
-                  <LiveApp action={dispatch} language={language}>
+                  <LiveApp
+                    action={(code: string) => dispatch(setStringRawBody(code))}
+                    language={language}
+                  >
                     {example.body}
                   </LiveApp>
                 )}
@@ -366,7 +342,11 @@ function Body({
 
   return (
     <FormItem>
-      <LiveApp action={dispatch} language={language} required={required}>
+      <LiveApp
+        action={(code: string) => dispatch(setStringRawBody(code))}
+        language={language}
+        required={required}
+      >
         {defaultBody}
       </LiveApp>
     </FormItem>

package/src/theme/ApiExplorer/Body/json2xml.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.
+ * ========================================================================== */
+
+export default function json2xml(input: any, indent?: any): any;

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

@@ -15,12 +15,24 @@ export interface FileContent {
   };
 }
 
+export interface FileArrayContent {
+  type: "file[]";
+  value: {
+    src: string;
+    content: Blob;
+  }[];
+}
+
 export interface StringContent {
   type: "string";
   value?: string;
 }
 
-export type Content = FileContent | StringContent | undefined;
+export type Content =
+  | FileContent
+  | FileArrayContent
+  | StringContent
+  | undefined;
 
 export interface FormBody {
   type: "form";
@@ -118,6 +130,32 @@ export const slice = createSlice({
       };
       return state;
     },
+    setFileArrayFormBody: (
+      state,
+      action: PayloadAction<{
+        key: string;
+        value: FileArrayContent["value"];
+      }>
+    ) => {
+      if (state?.type !== "form") {
+        return {
+          type: "form",
+          content: {
+            [action.payload.key]: {
+              type: "file[]",
+              value: action.payload.value,
+            },
+          },
+        };
+      }
+
+      state.content[action.payload.key] = {
+        type: "file[]",
+        value: action.payload.value,
+      };
+
+      return state;
+    },
   },
 });
 
@@ -128,6 +166,7 @@ export const {
   clearFormBodyKey,
   setStringFormBody,
   setFileFormBody,
+  setFileArrayFormBody,
 } = slice.actions;
 
 export default slice.reducer;

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

@@ -29,6 +29,7 @@ export const languageSet: Language[] = generateLanguageSet();
 export interface Props {
   postman: sdk.Request;
   codeSamples: CodeSample[];
+  maskCredentials?: boolean;
 }
 
 function CodeTab({ children, hidden, className }: any): React.JSX.Element {
@@ -39,7 +40,11 @@ function CodeTab({ children, hidden, className }: any): React.JSX.Element {
   );
 }
 
-function CodeSnippets({ postman, codeSamples }: Props) {
+function CodeSnippets({
+  postman,
+  codeSamples,
+  maskCredentials: propMaskCredentials,
+}: Props) {
   const { siteConfig } = useDocusaurusContext();
 
   const contentType = useTypedSelector((state: any) => state.contentType.value);
@@ -53,33 +58,42 @@ function CodeSnippets({ postman, codeSamples }: Props) {
   const headerParams = useTypedSelector((state: any) => state.params.header);
 
   const auth = useTypedSelector((state: any) => state.auth);
-  const clonedAuth = cloneDeep(auth);
-  let placeholder: string;
 
-  function cleanCredentials(obj: any) {
-    for (const key in obj) {
-      if (typeof obj[key] === "object" && obj[key] !== null) {
-        // use name as placeholder if exists
-        const comboAuthId = Object.keys(obj).join(" and ");
-        const authOptions =
-          clonedAuth?.options?.[key] ?? clonedAuth?.options?.[comboAuthId];
-        placeholder = authOptions?.[0]?.name;
-        obj[key] = cleanCredentials(obj[key]);
-      } else {
-        obj[key] = `<${placeholder ?? key}>`;
-      }
-    }
+  // Check if credential masking is enabled (default: true)
+  const maskCredentials = propMaskCredentials ?? true;
 
-    return obj;
-  }
+  // Clone Auth if maskCredentials is not false
+  const cleanedAuth = maskCredentials
+    ? (() => {
+        const clonedAuth = cloneDeep(auth);
+        let placeholder: string;
 
-  // scrub credentials from code snippets
-  const cleanedAuth = {
-    ...clonedAuth,
-    data: cleanCredentials(clonedAuth.data),
-  };
+        function cleanCredentials(obj: any) {
+          for (const key in obj) {
+            if (typeof obj[key] === "object" && obj[key] !== null) {
+              // use name as placeholder if exists
+              const comboAuthId = Object.keys(obj).join(" and ");
+              const authOptions =
+                clonedAuth?.options?.[key] ??
+                clonedAuth?.options?.[comboAuthId];
+              placeholder = authOptions?.find((opt: any) => opt.key === key)?.name;
+              obj[key] = cleanCredentials(obj[key]);
+            } else {
+              obj[key] = `<${placeholder ?? key}>`;
+            }
+          }
 
-  // Create a Postman request object using cleanedAuth
+          return obj;
+        }
+
+        return {
+          ...clonedAuth,
+          data: cleanCredentials(clonedAuth.data),
+        };
+      })()
+    : auth;
+
+  // Create a Postman request object using cleanedAuth or original auth
   const cleanedPostmanRequest = buildPostmanRequest(postman, {
     queryParams,
     pathParams,
@@ -127,9 +141,9 @@ function CodeSnippets({ postman, codeSamples }: Props) {
     return defaultLang[0] ?? mergedLangs[0];
   });
   const [codeText, setCodeText] = useState<string>("");
-  const [codeSampleCodeText, setCodeSampleCodeText] = useState<
-    string | (() => string)
-  >(() => getCodeSampleSourceFromLanguage(language));
+  const [codeSampleCodeText, setCodeSampleCodeText] = useState<string>(() =>
+    getCodeSampleSourceFromLanguage(language)
+  );
 
   useEffect(() => {
     if (language && !!language.sample) {
@@ -259,7 +273,7 @@ function CodeSnippets({ postman, codeSamples }: Props) {
                     setSelectedSample: setSelectedSample,
                   }}
                   includeSample={true}
-                  currentLanguage={lang.language}
+                  currentLanguage={lang}
                   defaultValue={selectedSample}
                   languageSet={mergedLangs}
                   lazy
@@ -300,7 +314,7 @@ function CodeSnippets({ postman, codeSamples }: Props) {
                   setSelectedVariant: setSelectedVariant,
                 }}
                 includeVariant={true}
-                currentLanguage={lang.language}
+                currentLanguage={lang}
                 defaultValue={selectedVariant}
                 languageSet={mergedLangs}
                 lazy

package/src/theme/ApiExplorer/CodeTabs/_CodeTabs.scss

@@ -197,7 +197,11 @@ body[class="ReactModal__Body--open"] {
   }
 
   &.active {
-    box-shadow: 0 0 0 3px var(--openapi-code-tab-shadow-color-curl);
+    box-shadow: 0 0 0 3px
+      var(
+        --openapi-code-tab-shadow-color-curl,
+        var(--openapi-code-tab-shadow-color-bash)
+      );
     border-color: var(--ifm-color-danger);
   }
 }

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

@@ -15,16 +15,17 @@ import {
 } from "@docusaurus/theme-common/internal";
 import { TabItemProps } from "@docusaurus/theme-common/lib/utils/tabsUtils";
 import useIsBrowser from "@docusaurus/useIsBrowser";
-import { Language } from "@theme/ApiExplorer/CodeSnippets";
 import clsx from "clsx";
 
+import { Language } from "../CodeSnippets/code-snippets-types";
+
 export interface Props {
   action: {
     [key: string]: React.Dispatch<any>;
   };
-  currentLanguage: Language;
+  currentLanguage?: Language;
   languageSet: Language[];
-  includeVariant: boolean;
+  includeVariant?: boolean;
 }
 
 export interface CodeTabsProps extends Props, TabProps {
@@ -94,13 +95,13 @@ function TabList({
       let newLanguage: Language;
       if (currentLanguage && includeVariant) {
         newLanguage = languageSet.filter(
-          (lang: Language) => lang.language === currentLanguage
+          (lang: Language) => lang.language === currentLanguage.language
         )[0];
         newLanguage.variant = newTabValue;
         action.setSelectedVariant(newTabValue.toLowerCase());
       } else if (currentLanguage && includeSample) {
         newLanguage = languageSet.filter(
-          (lang: Language) => lang.language === currentLanguage
+          (lang: Language) => lang.language === currentLanguage.language
         )[0];
         newLanguage.sample = newTabValue;
         action.setSelectedSample(newTabValue);

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

@@ -27,7 +27,7 @@ function ContentType() {
       <FormSelect
         value={value}
         options={options}
-        onChange={(e: React.ChangeEvent<HTMLInputElement>) =>
+        onChange={(e: React.ChangeEvent<HTMLSelectElement>) =>
           dispatch(setContentType(e.target.value))
         }
       />

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

@@ -7,7 +7,9 @@
 
 import React, { useState } from "react";
 
+import { translate } from "@docusaurus/Translate";
 import FloatingButton from "@theme/ApiExplorer/FloatingButton";
+import { OPENAPI_FORM_FILE_UPLOAD } from "@theme/translationIds";
 import MagicDropzone from "react-magic-dropzone";
 
 type PreviewFile = { preview: string } & File;
@@ -102,7 +104,10 @@ function FormFileUpload({ placeholder, onChange }: Props) {
                 setAndNotifyFile(undefined);
               }}
             >
-              Clear
+              {translate({
+                id: OPENAPI_FORM_FILE_UPLOAD.CLEAR_BUTTON,
+                message: "Clear",
+              })}
             </button>
             <RenderPreview file={file} />
           </>