docusaurus-theme-openapi-docs 4.5.1 → 4.7.0

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

@@ -0,0 +1,155 @@
+/* ============================================================================
+ * 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 { SchemaObject } from "docusaurus-plugin-openapi-docs/src/openapi/types";
+import merge from "lodash/merge";
+
+export interface SchemaSelections {
+  [schemaPath: string]: number;
+}
+
+/**
+ * Resolves a schema by replacing anyOf/oneOf with the selected option based on user selections.
+ *
+ * @param schema - The original schema object
+ * @param selections - Map of schema paths to selected indices
+ * @param basePath - The base path for this schema (used for looking up selections)
+ * @returns A new schema with anyOf/oneOf resolved to selected options
+ */
+export function resolveSchemaWithSelections(
+  schema: SchemaObject | undefined,
+  selections: SchemaSelections,
+  basePath: string = "requestBody"
+): SchemaObject | undefined {
+  if (!schema) {
+    return schema;
+  }
+
+  // Deep clone to avoid mutating the original schema
+  const schemaCopy = JSON.parse(JSON.stringify(schema)) as SchemaObject;
+
+  return resolveSchemaRecursive(schemaCopy, selections, basePath);
+}
+
+function resolveSchemaRecursive(
+  schema: SchemaObject,
+  selections: SchemaSelections,
+  currentPath: string
+): SchemaObject {
+  // Handle oneOf
+  if (schema.oneOf && Array.isArray(schema.oneOf)) {
+    const selectedIndex = selections[currentPath] ?? 0;
+    const selectedSchema = schema.oneOf[selectedIndex] as SchemaObject;
+
+    if (selectedSchema) {
+      // If there are shared properties, merge them with the selected schema
+      if (schema.properties) {
+        const mergedSchema = merge({}, schema, selectedSchema);
+        delete mergedSchema.oneOf;
+
+        // Continue resolving nested schemas in the merged result
+        return resolveSchemaRecursive(
+          mergedSchema,
+          selections,
+          `${currentPath}.${selectedIndex}`
+        );
+      }
+
+      // No shared properties, just use the selected schema
+      // Continue resolving in case there are nested anyOf/oneOf
+      return resolveSchemaRecursive(
+        selectedSchema,
+        selections,
+        `${currentPath}.${selectedIndex}`
+      );
+    }
+  }
+
+  // Handle anyOf
+  if (schema.anyOf && Array.isArray(schema.anyOf)) {
+    const selectedIndex = selections[currentPath] ?? 0;
+    const selectedSchema = schema.anyOf[selectedIndex] as SchemaObject;
+
+    if (selectedSchema) {
+      // If there are shared properties, merge them with the selected schema
+      if (schema.properties) {
+        const mergedSchema = merge({}, schema, selectedSchema);
+        delete mergedSchema.anyOf;
+
+        // Continue resolving nested schemas in the merged result
+        return resolveSchemaRecursive(
+          mergedSchema,
+          selections,
+          `${currentPath}.${selectedIndex}`
+        );
+      }
+
+      // No shared properties, just use the selected schema
+      // Continue resolving in case there are nested anyOf/oneOf
+      return resolveSchemaRecursive(
+        selectedSchema,
+        selections,
+        `${currentPath}.${selectedIndex}`
+      );
+    }
+  }
+
+  // Handle allOf - merge all schemas and continue resolving
+  if (schema.allOf && Array.isArray(schema.allOf)) {
+    // Process each allOf item, resolving any anyOf/oneOf within them
+    const resolvedItems = schema.allOf.map((item, index) => {
+      return resolveSchemaRecursive(
+        item as SchemaObject,
+        selections,
+        `${currentPath}.allOf.${index}`
+      );
+    });
+
+    // Merge all resolved items
+    const mergedSchema = resolvedItems.reduce(
+      (acc, item) => merge(acc, item),
+      {} as SchemaObject
+    );
+
+    // Preserve any top-level properties from the original schema
+    if (schema.properties) {
+      mergedSchema.properties = merge(
+        {},
+        mergedSchema.properties,
+        schema.properties
+      );
+    }
+
+    return mergedSchema;
+  }
+
+  // Handle object properties recursively
+  if (schema.properties) {
+    const resolvedProperties: { [key: string]: SchemaObject } = {};
+
+    for (const [propName, propSchema] of Object.entries(schema.properties)) {
+      resolvedProperties[propName] = resolveSchemaRecursive(
+        propSchema as SchemaObject,
+        selections,
+        `${currentPath}.${propName}`
+      );
+    }
+
+    schema.properties = resolvedProperties;
+  }
+
+  // Handle array items recursively
+  if (schema.items) {
+    schema.items = resolveSchemaRecursive(
+      schema.items as SchemaObject,
+      selections,
+      `${currentPath}.items`
+    );
+  }
+
+  return schema;
+}

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} />
           </>

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

@@ -7,6 +7,9 @@
 
 import React from "react";
 
+import { translate } from "@docusaurus/Translate";
+import { OPENAPI_SCHEMA_ITEM } from "@theme/translationIds";
+
 import clsx from "clsx";
 
 export interface Props {
@@ -24,7 +27,11 @@ function FormItem({ label, type, required, children, className }: Props) {
         <label className="openapi-explorer__form-item-label">{label}</label>
       )}
       {type && <span style={{ opacity: 0.6 }}> — {type}</span>}
-      {required && <span className="openapi-schema__required">required</span>}
+      {required && (
+        <span className="openapi-schema__required">
+          {translate({ id: OPENAPI_SCHEMA_ITEM.REQUIRED, message: "required" })}
+        </span>
+      )}
       <div>{children}</div>
     </div>
   );

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

@@ -8,7 +8,9 @@
 // @ts-nocheck
 import React from "react";
 
+import { translate } from "@docusaurus/Translate";
 import { ErrorMessage } from "@hookform/error-message";
+import { OPENAPI_FORM } from "@theme/translationIds";
 import clsx from "clsx";
 import { useFormContext } from "react-hook-form";
 
@@ -17,6 +19,8 @@ export interface Props {
   placeholder?: string;
   password?: boolean;
   onChange?: React.ChangeEventHandler<HTMLInputElement>;
+  paramName?: string;
+  isRequired?: boolean;
 }
 
 function FormTextInput({
@@ -41,7 +45,12 @@ function FormTextInput({
       {paramName ? (
         <input
           {...register(paramName, {
-            required: isRequired ? "This field is required" : false,
+            required: isRequired
+              ? translate({
+                  id: OPENAPI_FORM.FIELD_REQUIRED,
+                  message: "This field is required",
+                })
+              : false,
           })}
           className={clsx("openapi-explorer__form-item-input", {
             error: showErrorMessage,

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

@@ -8,9 +8,10 @@
 import React, { type JSX, useEffect, useState } from "react";
 
 import { usePrismTheme } from "@docusaurus/theme-common";
+import { translate } from "@docusaurus/Translate";
 import useIsBrowser from "@docusaurus/useIsBrowser";
 import { ErrorMessage } from "@hookform/error-message";
-import { setStringRawBody } from "@theme/ApiExplorer/Body/slice";
+import { OPENAPI_FORM } from "@theme/translationIds";
 import clsx from "clsx";
 import { Controller, useFormContext } from "react-hook-form";
 import { LiveProvider, LiveEditor, withLive } from "react-live";
@@ -54,8 +55,8 @@ function App({
   const [code, setCode] = React.useState(children.replace(/\n$/, ""));
 
   useEffect(() => {
-    action(setStringRawBody(code));
-  }, [action, code]);
+    action(code);
+  }, [code]);
 
   const {
     control,
@@ -85,7 +86,13 @@ function App({
         <Controller
           control={control}
           rules={{
-            required: isRequired && !code ? "This field is required" : false,
+            required:
+              isRequired && !code
+                ? translate({
+                    id: OPENAPI_FORM.FIELD_REQUIRED,
+                    message: "This field is required",
+                  })
+                : false,
           }}
           name="requestBody"
           render={({ field: { onChange, name } }) => (

package/src/theme/ApiExplorer/ParamOptions/ParamFormItems/ParamArrayFormItem.tsx

@@ -7,12 +7,14 @@
 
 import React, { useEffect, useState } from "react";
 
+import { translate } from "@docusaurus/Translate";
 import { ErrorMessage } from "@hookform/error-message";
 import { nanoid } from "@reduxjs/toolkit";
 import FormSelect from "@theme/ApiExplorer/FormSelect";
 import FormTextInput from "@theme/ApiExplorer/FormTextInput";
 import { Param, setParam } from "@theme/ApiExplorer/ParamOptions/slice";
 import { useTypedDispatch } from "@theme/ApiItem/hooks";
+import { OPENAPI_FORM } from "@theme/translationIds";
 import { Controller, useFormContext } from "react-hook-form";
 
 export interface ParamProps {
@@ -30,7 +32,7 @@ function ArrayItem({
     return (
       <FormSelect
         options={["---", "true", "false"]}
-        onChange={(e: React.ChangeEvent<HTMLInputElement>) => {
+        onChange={(e: React.ChangeEvent<HTMLSelectElement>) => {
           const val = e.target.value;
           onChange(val === "---" ? undefined : val);
         }}
@@ -87,15 +89,16 @@ export default function ParamArrayFormItem({ param }: ParamProps) {
   }, [items]);
 
   useEffect(() => {
-    if (param.schema?.example?.length > 0) {
-      const examplesWithIds = param.schema.example.map((item: any) => ({
+    const example = param.schema?.example;
+    if (Array.isArray(example) && example.length > 0) {
+      const examplesWithIds = example.map((item: any) => ({
         id: nanoid(),
         value: item.toString(),
       }));
 
       setItems(examplesWithIds);
     }
-  }, [param.schema.example, param.schema.length]);
+  }, [param.schema?.example]);
 
   function handleDeleteItem(itemToDelete: { id: string }) {
     return () => {
@@ -121,9 +124,16 @@ export default function ParamArrayFormItem({ param }: ParamProps) {
     <>
       <Controller
         control={control}
-        rules={{ required: param.required ? "This field is required" : false }}
+        rules={{
+          required: param.required
+            ? translate({
+                id: OPENAPI_FORM.FIELD_REQUIRED,
+                message: "This field is required",
+              })
+            : false,
+        }}
         name="paramArray"
-        render={({ field: { onChange, name } }) => (
+        render={({ field: { onChange } }) => (
           <>
             {items.map((item) => (
               <div key={item.id} style={{ display: "flex" }}>

package/src/theme/ApiExplorer/ParamOptions/ParamFormItems/ParamBooleanFormItem.tsx

@@ -7,10 +7,12 @@
 
 import React from "react";
 
+import { translate } from "@docusaurus/Translate";
 import { ErrorMessage } from "@hookform/error-message";
 import FormSelect from "@theme/ApiExplorer/FormSelect";
 import { Param, setParam } from "@theme/ApiExplorer/ParamOptions/slice";
 import { useTypedDispatch } from "@theme/ApiItem/hooks";
+import { OPENAPI_FORM } from "@theme/translationIds";
 import { Controller, useFormContext } from "react-hook-form";
 
 export interface ParamProps {
@@ -31,13 +33,19 @@ export default function ParamBooleanFormItem({ param }: ParamProps) {
     <>
       <Controller
         control={control}
-        rules={{ required: param.required ? "This field is required" : false }}
+        rules={{
+          required: param.required
+            ? translate({
+                id: OPENAPI_FORM.FIELD_REQUIRED,
+                message: "This field is required",
+              })
+            : false,
+        }}
         name="paramBoolean"
-        render={({ field: { onChange, name } }) => (
+        render={({ field: { onChange } }) => (
           <FormSelect
-            name={name}
             options={["---", "true", "false"]}
-            onChange={(e: React.ChangeEvent<HTMLInputElement>) => {
+            onChange={(e: React.ChangeEvent<HTMLSelectElement>) => {
               const val = e.target.value;
               dispatch(
                 setParam({

package/src/theme/ApiExplorer/ParamOptions/ParamFormItems/ParamMultiSelectFormItem.tsx

@@ -7,10 +7,12 @@
 
 import React from "react";
 
+import { translate } from "@docusaurus/Translate";
 import { ErrorMessage } from "@hookform/error-message";
 import FormMultiSelect from "@theme/ApiExplorer/FormMultiSelect";
 import { Param, setParam } from "@theme/ApiExplorer/ParamOptions/slice";
 import { useTypedDispatch, useTypedSelector } from "@theme/ApiItem/hooks";
+import { OPENAPI_FORM } from "@theme/translationIds";
 import { Controller, useFormContext } from "react-hook-form";
 
 export interface ParamProps {
@@ -61,14 +63,20 @@ export default function ParamMultiSelectFormItem({ param }: ParamProps) {
     <>
       <Controller
         control={control}
-        rules={{ required: param.required ? "This field is required" : false }}
+        rules={{
+          required: param.required
+            ? translate({
+                id: OPENAPI_FORM.FIELD_REQUIRED,
+                message: "This field is required",
+              })
+            : false,
+        }}
         name="paramMultiSelect"
-        render={({ field: { onChange, name } }) => (
+        render={({ field: { onChange } }) => (
           <FormMultiSelect
             options={options as string[]}
-            name={name}
             onChange={(e: any) => handleChange(e, onChange)}
-            showErrors={showErrorMessage}
+            showErrors={!!showErrorMessage}
           />
         )}
       />