docusaurus-theme-openapi-docs 4.5.0 → 4.6.0

package/src/theme/ApiExplorer/buildPostmanRequest.ts

@@ -55,20 +55,10 @@ function setQueryParams(postman: sdk.Request, queryParams: Param[]) {
         }
       }
 
-      const decodedValue = decodeURI(param.value);
-      const tryJson = () => {
-        try {
-          return JSON.parse(decodedValue);
-        } catch (e) {
-          return false;
-        }
-      };
-
-      const jsonResult = tryJson();
-
       // Handle object values
-      if (jsonResult && typeof jsonResult === "object") {
-        if (param.style === "deepObject") {
+      if (param.style === "deepObject") {
+        const jsonResult = tryDecodeJsonParam(param.value);
+        if (jsonResult && typeof jsonResult === "object") {
           return Object.entries(jsonResult).map(
             ([key, val]) =>
               new sdk.QueryParam({
@@ -76,7 +66,10 @@ function setQueryParams(postman: sdk.Request, queryParams: Param[]) {
                 value: String(val),
               })
           );
-        } else if (param.explode) {
+        }
+      } else if (param.explode) {
+        const jsonResult = tryDecodeJsonParam(param.value);
+        if (jsonResult && typeof jsonResult === "object") {
           return Object.entries(jsonResult).map(
             ([key, val]) =>
               new sdk.QueryParam({
@@ -94,17 +87,9 @@ function setQueryParams(postman: sdk.Request, queryParams: Param[]) {
         }
       }
 
-      // Handle boolean values
-      if (typeof decodedValue === "boolean") {
-        return new sdk.QueryParam({
-          key: param.name,
-          value: decodedValue ? "true" : "false",
-        });
-      }
-
       // Parameter allows empty value: "/hello?extended"
       if (param.allowEmptyValue) {
-        if (decodedValue === "true") {
+        if (param.value === "true") {
           return new sdk.QueryParam({
             key: param.name,
             value: null,
@@ -150,18 +135,9 @@ function setPathParams(postman: sdk.Request, pathParams: Param[]) {
       });
     }
 
-    const decodedValue = decodeURI(param.value);
-    const tryJson = () => {
-      try {
-        return JSON.parse(decodedValue);
-      } catch (e) {
-        return false;
-      }
-    };
+    const jsonResult = tryDecodeJsonParam(param.value);
 
-    const jsonResult = tryJson();
-
-    if (typeof jsonResult === "object") {
+    if (jsonResult && typeof jsonResult === "object") {
       if (param.style === "matrix") {
         serializedValue = Object.entries(jsonResult)
           .map(([key, val]) => `;${key}=${val}`)
@@ -172,7 +148,7 @@ function setPathParams(postman: sdk.Request, pathParams: Param[]) {
           .join(",");
       }
     } else {
-      serializedValue = decodedValue || `:${param.name}`;
+      serializedValue = param.value;
     }
 
     return new sdk.Variable({
@@ -191,17 +167,8 @@ function buildCookie(cookieParams: Param[]) {
   const cookies = cookieParams
     .map((param) => {
       if (param.value) {
-        const decodedValue = decodeURI(param.value as string);
-        const tryJson = () => {
-          try {
-            return JSON.parse(decodedValue);
-          } catch (e) {
-            return false;
-          }
-        };
-
-        const jsonResult = tryJson();
-        if (typeof jsonResult === "object") {
+        const jsonResult = tryDecodeJsonParam(param.value as string);
+        if (jsonResult && typeof jsonResult === "object") {
           if (param.style === "form") {
             // Handle form style
             if (param.explode) {
@@ -266,16 +233,9 @@ function setHeaders(
 
   headerParams.forEach((param) => {
     if (param.value) {
-      const decodedValue = decodeURI(param.value as string);
-      const tryJson = () => {
-        try {
-          return JSON.parse(decodedValue);
-        } catch (e) {
-          return false;
-        }
-      };
-
-      const jsonResult = tryJson();
+      const jsonResult = Array.isArray(param.value)
+        ? param.value.map(tryDecodeJsonParam)
+        : tryDecodeJsonParam(param.value);
       if (Array.isArray(param.value)) {
         if (param.style === "simple") {
           if (param.explode) {
@@ -324,6 +284,14 @@ function setHeaders(
   }
 }
 
+function tryDecodeJsonParam(value: string): any {
+  try {
+    return JSON.parse(decodeURI(value));
+  } catch (e) {
+    return false;
+  }
+}
+
 // TODO: this is all a bit hacky
 function setBody(clonedPostman: sdk.Request, body: Body) {
   if (clonedPostman.body === undefined) {
@@ -345,7 +313,11 @@ function setBody(clonedPostman: sdk.Request, body: Body) {
   switch (clonedPostman.body.mode) {
     case "raw": {
       // check file even though it should already be set from above
-      if (body.type !== "raw" || body.content?.type === "file") {
+      if (
+        body.type !== "raw" ||
+        body.content?.type === "file" ||
+        body.content?.type === "file[]"
+      ) {
         clonedPostman.body = undefined;
         return;
       }
@@ -360,15 +332,23 @@ function setBody(clonedPostman: sdk.Request, body: Body) {
         clonedPostman.body.raw = `${body.content?.value}`;
         return;
       }
-      const params = Object.entries(body.content)
+      const params: sdk.FormParam[] = [];
+      Object.entries(body.content)
         .filter((entry): entry is [string, NonNullable<Content>] => !!entry[1])
-        .map(([key, content]) => {
+        .forEach(([key, content]) => {
           if (content.type === "file") {
-            return new sdk.FormParam({ key: key, ...content });
+            params.push(new sdk.FormParam({ key: key, ...content }));
+          } else if (content.type === "file[]") {
+            content.value.forEach((file) =>
+              params.push(new sdk.FormParam({ key, value: file }))
+            );
+          } else {
+            params.push(new sdk.FormParam({ key: key, value: content.value }));
           }
-          return new sdk.FormParam({ key: key, value: content.value });
         });
-      clonedPostman.body.formdata?.assimilate(params, false);
+      params.forEach((param) => {
+        clonedPostman.body?.formdata?.add(param);
+      });
       return;
     }
     case "urlencoded": {
@@ -382,7 +362,11 @@ function setBody(clonedPostman: sdk.Request, body: Body) {
       const params = Object.entries(body.content)
         .filter((entry): entry is [string, NonNullable<Content>] => !!entry[1])
         .map(([key, content]) => {
-          if (content.type !== "file" && content.value) {
+          if (
+            content.type !== "file" &&
+            content.type !== "file[]" &&
+            content.value
+          ) {
             return new sdk.QueryParam({ key: key, value: content.value });
           }
           return undefined;

package/src/theme/ApiExplorer/index.tsx

@@ -7,6 +7,7 @@
 
 import React from "react";
 
+import { useDoc } from "@docusaurus/plugin-content-docs/client";
 import CodeSnippets from "@theme/ApiExplorer/CodeSnippets";
 import Request from "@theme/ApiExplorer/Request";
 import Response from "@theme/ApiExplorer/Response";
@@ -21,8 +22,15 @@ function ApiExplorer({
   item: NonNullable<ApiItem>;
   infoPath: string;
 }) {
+  const metadata = useDoc();
+  const { mask_credentials } = metadata.frontMatter;
+
   const postman = new sdk.Request(
-    item.postman ? (item.postman as any).toJSON() : {}
+    item.postman
+      ? sdk.Request.isRequest(item.postman)
+        ? (item.postman as any).toJSON()
+        : (item.postman as any)
+      : {}
   );
 
   return (
@@ -32,6 +40,7 @@ function ApiExplorer({
         <CodeSnippets
           postman={postman}
           codeSamples={(item as any)["x-codeSamples"] ?? []}
+          maskCredentials={mask_credentials}
         />
       )}
       <Request item={item} />

package/src/theme/ApiExplorer/{persistanceMiddleware.ts → persistenceMiddleware.ts}

@@ -5,25 +5,29 @@
  * LICENSE file in the root directory of this source tree.
  * ========================================================================== */
 
-import { Middleware } from "@reduxjs/toolkit";
+import type { Middleware } from "@reduxjs/toolkit";
 import {
   setAuthData,
   setSelectedAuth,
 } from "@theme/ApiExplorer/Authorization/slice";
-import { AppDispatch, RootState } from "@theme/ApiItem/store";
-/* eslint-disable import/no-extraneous-dependencies*/
-import { ThemeConfig } from "docusaurus-theme-openapi-docs/src/types";
+import type { AppDispatch, RootState } from "@theme/ApiItem/store";
+import type { ServerObject } from "docusaurus-plugin-openapi-docs/src/openapi/types";
+import type { ThemeConfig } from "docusaurus-theme-openapi-docs/src/types";
 
 import { createStorage, hashArray } from "./storage-utils";
 
-export function createPersistanceMiddleware(options: ThemeConfig["api"]) {
-  const persistanceMiddleware: Middleware<{}, RootState, AppDispatch> =
-    (storeAPI) => (next) => (action) => {
+export function createPersistenceMiddleware(options: ThemeConfig["api"]) {
+  const persistenceMiddleware: Middleware<{}, RootState, AppDispatch> =
+    (storeAPI) =>
+    (next) =>
+    (action: ReturnType<typeof setAuthData | typeof setSelectedAuth> | any) => {
       const result = next(action);
 
       const state = storeAPI.getState();
 
-      const storage = createStorage("sessionStorage");
+      const storage = createStorage(
+        options?.authPersistence ?? "sessionStorage"
+      );
 
       if (action.type === setAuthData.type) {
         for (const [key, value] of Object.entries(state.auth.data)) {
@@ -58,14 +62,20 @@ export function createPersistanceMiddleware(options: ThemeConfig["api"]) {
       }
 
       if (action.type === "server/setServerVariable") {
-        const server = storage.getItem("server") ?? "{}";
+        const server = storage.getItem("server");
+        if (!server) {
+          return result;
+        }
         const variables = JSON.parse(action.payload);
-        let serverObject = JSON.parse(server);
-        serverObject.variables[variables.key].default = variables.value;
-        storage.setItem("server", JSON.stringify(serverObject));
+
+        const serverObject = (JSON.parse(server) as ServerObject) ?? {};
+        if (serverObject.variables?.[variables.key]) {
+          serverObject.variables[variables.key].default = variables.value;
+          storage.setItem("server", JSON.stringify(serverObject));
+        }
       }
 
       return result;
     };
-  return persistanceMiddleware;
+  return persistenceMiddleware;
 }

package/src/theme/ApiExplorer/storage-utils.ts

@@ -17,10 +17,10 @@ export function hashArray(arr: string[]) {
   return hash(res);
 }
 
-type Persistance = false | "localStorage" | "sessionStorage" | undefined;
+type Persistence = false | "localStorage" | "sessionStorage" | undefined;
 
-export function createStorage(persistance: Persistance): Storage {
-  if (persistance === false) {
+export function createStorage(persistence: Persistence): Storage {
+  if (persistence === false) {
     return {
       getItem: () => null,
       setItem: () => {},
@@ -31,7 +31,7 @@ export function createStorage(persistance: Persistance): Storage {
     };
   }
 
-  if (persistance === "sessionStorage") {
+  if (persistence === "sessionStorage") {
     return sessionStorage;
   }
 

package/src/theme/ApiItem/Layout/index.tsx

@@ -9,11 +9,11 @@ import React, { type JSX } from "react";
 
 import { useDoc } from "@docusaurus/plugin-content-docs/client";
 import { useWindowSize } from "@docusaurus/theme-common";
-import type { Props } from "@theme/ApiItem/Layout";
 import ContentVisibility from "@theme/ContentVisibility";
 import DocBreadcrumbs from "@theme/DocBreadcrumbs";
 import DocItemContent from "@theme/DocItem/Content";
 import DocItemFooter from "@theme/DocItem/Footer";
+import type { Props } from "@theme/DocItem/Layout";
 import DocItemPaginator from "@theme/DocItem/Paginator";
 import DocItemTOCDesktop from "@theme/DocItem/TOC/Desktop";
 import DocItemTOCMobile from "@theme/DocItem/TOC/Mobile";

package/src/theme/ApiItem/index.tsx

@@ -14,7 +14,8 @@ import { HtmlClassNameProvider } from "@docusaurus/theme-common";
 import useDocusaurusContext from "@docusaurus/useDocusaurusContext";
 import useIsBrowser from "@docusaurus/useIsBrowser";
 import { createAuth } from "@theme/ApiExplorer/Authorization/slice";
-import { createPersistanceMiddleware } from "@theme/ApiExplorer/persistanceMiddleware";
+import { createPersistenceMiddleware } from "@theme/ApiExplorer/persistenceMiddleware";
+import { createStorage } from "@theme/ApiExplorer/storage-utils";
 import DocItemLayout from "@theme/ApiItem/Layout";
 import CodeBlock from "@theme/CodeBlock";
 import type { Props } from "@theme/DocItem";
@@ -90,11 +91,11 @@ export default function ApiItem(props: Props): JSX.Element {
 
   // Define store2
   let store2: any = {};
-  const persistanceMiddleware = createPersistanceMiddleware(options);
+  const persistenceMiddleware = createPersistenceMiddleware(options);
 
   // Init store for SSR
   if (!isBrowser) {
-    store2 = createStoreWithoutState({}, [persistanceMiddleware]);
+    store2 = createStoreWithoutState({}, [persistenceMiddleware]);
   }
 
   // Init store for CSR to hydrate components
@@ -129,11 +130,15 @@ export default function ApiItem(props: Props): JSX.Element {
       securitySchemes: api?.securitySchemes,
       options,
     });
+
+    const storage = createStorage(options?.authPersistence ?? "sessionStorage");
     // TODO: determine way to rehydrate without flashing
     // const acceptValue = window?.sessionStorage.getItem("accept");
     // const contentTypeValue = window?.sessionStorage.getItem("contentType");
-    const server = window?.sessionStorage.getItem("server");
-    const serverObject = (JSON.parse(server!) as ServerObject) ?? {};
+    const server = storage.getItem("server");
+    const serverObject = server
+      ? (JSON.parse(server) as ServerObject)
+      : undefined;
 
     store2 = createStoreWithState(
       {
@@ -146,7 +151,7 @@ export default function ApiItem(props: Props): JSX.Element {
           options: contentTypeArray,
         },
         server: {
-          value: serverObject.url ? serverObject : undefined,
+          value: serverObject?.url ? serverObject : undefined,
           options: servers,
         },
         response: { value: undefined },
@@ -154,7 +159,7 @@ export default function ApiItem(props: Props): JSX.Element {
         params,
         auth,
       },
-      [persistanceMiddleware]
+      [persistenceMiddleware]
     );
   }
 

package/src/theme/ApiTabs/index.tsx

@@ -20,8 +20,10 @@ import {
   useTabs,
 } from "@docusaurus/theme-common/internal";
 import { TabItemProps } from "@docusaurus/theme-common/lib/utils/tabsUtils";
+import { translate } from "@docusaurus/Translate";
 import useIsBrowser from "@docusaurus/useIsBrowser";
 import Heading from "@theme/Heading";
+import { OPENAPI_TABS } from "@theme/translationIds";
 import clsx from "clsx";
 
 export interface TabListProps extends TabProps {
@@ -35,7 +37,10 @@ function TabList({
   selectedValue,
   selectValue,
   tabValues,
-  label = "Responses",
+  label = translate({
+    id: OPENAPI_TABS.RESPONSES_LABEL,
+    message: "Responses",
+  }),
   id = "responses",
 }: TabListProps & ReturnType<typeof useTabs>) {
   const tabRefs: (HTMLLIElement | null)[] = [];

package/src/theme/Example/_Example.scss

@@ -0,0 +1,11 @@
+.openapi-examples {
+  > .openapi-tabs__schema-container {
+    margin: 0.4rem;
+
+    @layer docusaurus.infima {
+      > .margin-top--md {
+        margin: 0.2rem !important;
+      }
+    }
+  }
+}

package/src/theme/Example/index.tsx

@@ -0,0 +1,168 @@
+/* ============================================================================
+ * 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 { translate } from "@docusaurus/Translate";
+import { ExampleObject } from "@theme/ParamsItem";
+import SchemaTabs from "@theme/SchemaTabs";
+import TabItem from "@theme/TabItem";
+import { OPENAPI_SCHEMA_ITEM } from "@theme/translationIds";
+
+const EXAMPLE_CLASS_NAME = "openapi-example";
+const EXAMPLES_CLASS_NAME = "openapi-examples";
+
+type ExampleType = string;
+type ExamplesType = Record<string, ExampleObject> | string[];
+
+/**
+ * Example Component Props
+ */
+type ExampleProps = {
+  example?: ExampleType;
+  examples?: ExamplesType;
+};
+
+/**
+ * Example Component
+ */
+export const Example = ({ example, examples }: ExampleProps) => {
+  if (example !== undefined) {
+    return renderExample(example);
+  }
+  if (examples !== undefined) {
+    return renderExamples(examples);
+  }
+  return undefined;
+};
+
+/**
+ * Format example value
+ *
+ * @param example
+ * @returns
+ */
+const formatExample = (example: any) => {
+  if (typeof example === "object" && example !== null) {
+    return JSON.stringify(example);
+  }
+  return String(example);
+};
+
+const renderExample = (example: ExampleType) => {
+  return (
+    <div className={EXAMPLE_CLASS_NAME}>
+      <strong>
+        {translate({
+          id: OPENAPI_SCHEMA_ITEM.EXAMPLE,
+          message: "Example:",
+        })}{" "}
+      </strong>
+      <span>
+        <code>{formatExample(example)}</code>
+      </span>
+    </div>
+  );
+};
+
+const renderExamples = (examples: ExamplesType) => {
+  if (Array.isArray(examples)) {
+    return renderStringArrayExamples(examples);
+  }
+  return renderExamplesRecord(examples);
+};
+
+/**
+ * Render string examples
+ *
+ * @param examples
+ * @returns
+ */
+export function renderStringArrayExamples(examples: string[]) {
+  if (examples.length === 0) {
+    return undefined;
+  }
+  // If there's only one example, display it without tabs
+  if (examples.length === 1) {
+    return renderExample(examples[0]);
+  }
+
+  // Multiple examples - use tabs
+  const exampleEntries = examples.reduce(
+    (acc, example, index) => ({
+      ...acc,
+      [`Example ${index + 1}`]: {
+        value: example,
+      },
+    }),
+    {} as Record<string, ExampleObject>
+  );
+  return renderExamplesRecord(exampleEntries);
+}
+
+export const renderExamplesRecord = (
+  examples: Record<string, ExampleObject>
+) => {
+  const exampleEntries = Object.entries(examples);
+  // If there's only one example, display it without tabs
+  if (exampleEntries.length === 1) {
+    const firstExample = exampleEntries[0][1];
+    if (!firstExample) {
+      return undefined;
+    }
+    return renderExample(firstExample.value);
+  }
+
+  return (
+    <div className={EXAMPLES_CLASS_NAME}>
+      <strong>
+        {translate({
+          id: OPENAPI_SCHEMA_ITEM.EXAMPLES,
+          message: "Examples:",
+        })}
+      </strong>
+      <SchemaTabs>
+        {exampleEntries.map(([exampleName, exampleProperties]) =>
+          renderExampleObject(exampleName, exampleProperties)
+        )}
+      </SchemaTabs>
+    </div>
+  );
+};
+
+/**
+ * Render example object
+ *
+ * @param exampleName
+ * @param exampleProperties
+ * @returns
+ */
+const renderExampleObject = (
+  exampleName: string,
+  exampleProperties: ExampleObject
+) => {
+  return (
+    // @ts-ignore
+    <TabItem value={exampleName} label={exampleName}>
+      {exampleProperties.summary && <p>{exampleProperties.summary}</p>}
+      {exampleProperties.description && (
+        <p>
+          <strong>
+            {translate({
+              id: OPENAPI_SCHEMA_ITEM.DESCRIPTION,
+              message: "Description:",
+            })}{" "}
+          </strong>
+          <span>{exampleProperties.description}</span>
+        </p>
+      )}
+      {exampleProperties.value !== undefined
+        ? renderExample(exampleProperties.value)
+        : undefined}
+    </TabItem>
+  );
+};

package/src/theme/Markdown/index.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 Markdown(props: any): JSX.Element;

package/src/theme/ParamsDetails/index.tsx

@@ -7,6 +7,9 @@
 
 import React from "react";
 
+import { translate } from "@docusaurus/Translate";
+import { OPENAPI_PARAMS_DETAILS } from "@theme/translationIds";
+
 import BrowserOnly from "@docusaurus/BrowserOnly";
 import Details from "@theme/Details";
 import ParamsItem from "@theme/ParamsItem";
@@ -31,7 +34,13 @@ const ParamsDetailsComponent: React.FC<Props> = ({ parameters }) => {
         const summaryElement = (
           <summary>
             <h3 className="openapi-markdown__details-summary-header-params">
-              {`${type.charAt(0).toUpperCase() + type.slice(1)} Parameters`}
+              {translate(
+                {
+                  id: OPENAPI_PARAMS_DETAILS.PARAMETERS_TITLE,
+                  message: "{type} Parameters",
+                },
+                { type: type.charAt(0).toUpperCase() + type.slice(1) }
+              )}
             </h3>
           </summary>
         );