docusaurus-theme-openapi-docs 4.5.1 → 4.7.0

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,15 +151,16 @@ 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 },
         body: { type: "empty" },
         params,
         auth,
+        schemaSelection: { selections: {} },
       },
-      [persistanceMiddleware]
+      [persistenceMiddleware]
     );
   }
 

package/src/theme/ApiItem/store.ts

@@ -12,6 +12,7 @@ import body from "@theme/ApiExplorer/Body/slice";
 import contentType from "@theme/ApiExplorer/ContentType/slice";
 import params from "@theme/ApiExplorer/ParamOptions/slice";
 import response from "@theme/ApiExplorer/Response/slice";
+import schemaSelection from "@theme/ApiExplorer/SchemaSelection/slice";
 import server from "@theme/ApiExplorer/Server/slice";
 
 const rootReducer = combineReducers({
@@ -22,6 +23,7 @@ const rootReducer = combineReducers({
   body,
   params,
   auth,
+  schemaSelection,
 });
 
 export type RootState = ReturnType<typeof rootReducer>;

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>
         );

package/src/theme/ParamsItem/index.tsx

@@ -7,14 +7,15 @@
 
 import React from "react";
 
+import { translate } from "@docusaurus/Translate";
+import { Example } from "@theme/Example";
 import Markdown from "@theme/Markdown";
-import SchemaTabs from "@theme/SchemaTabs";
-import TabItem from "@theme/TabItem";
 /* eslint-disable import/no-extraneous-dependencies*/
+import { OPENAPI_SCHEMA_ITEM } from "@theme/translationIds";
 import clsx from "clsx";
 
 import { getQualifierMessage, getSchemaName } from "../../markdown/schema";
-import { guard, toString } from "../../markdown/utils";
+import { guard } from "../../markdown/utils";
 
 export interface ExampleObject {
   summary?: string;
@@ -28,7 +29,7 @@ export interface Props {
   param: {
     description: string;
     example: any;
-    examples: Record<string, ExampleObject>;
+    examples: Record<string, ExampleObject> | undefined;
     name: string;
     required: boolean;
     deprecated: boolean;
@@ -39,7 +40,15 @@ export interface Props {
 
 const getEnumDescriptionMarkdown = (enumDescriptions?: [string, string][]) => {
   if (enumDescriptions?.length) {
-    return `| Enum Value | Description |
+    const enumValue = translate({
+      id: OPENAPI_SCHEMA_ITEM.ENUM_VALUE,
+      message: "Enum Value",
+    });
+    const description = translate({
+      id: OPENAPI_SCHEMA_ITEM.ENUM_DESCRIPTION,
+      message: "Description",
+    });
+    return `| ${enumValue} | ${description} |
 | ---- | ----- |
 ${enumDescriptions
   .map((desc) => {
@@ -53,19 +62,14 @@ ${enumDescriptions
 };
 
 function ParamsItem({ param, ...rest }: Props) {
-  const {
-    description,
-    example,
-    examples,
-    name,
-    required,
-    deprecated,
-    enumDescriptions,
-  } = param;
+  const { description, name, required, deprecated, enumDescriptions } = param;
 
   let schema = param.schema;
   let defaultValue: string | undefined;
 
+  let examples = param.examples ?? (schema?.examples as any[] | undefined);
+  let example = param.example ?? schema?.example;
+
   if (!schema) {
     schema = { type: "any" };
   }
@@ -87,11 +91,15 @@ function ParamsItem({ param, ...rest }: Props) {
   ));
 
   const renderSchemaRequired = guard(required, () => (
-    <span className="openapi-schema__required">required</span>
+    <span className="openapi-schema__required">
+      {translate({ id: OPENAPI_SCHEMA_ITEM.REQUIRED, message: "required" })}
+    </span>
   ));
 
   const renderDeprecated = guard(deprecated, () => (
-    <span className="openapi-schema__deprecated">deprecated</span>
+    <span className="openapi-schema__deprecated">
+      {translate({ id: OPENAPI_SCHEMA_ITEM.DEPRECATED, message: "deprecated" })}
+    </span>
   ));
 
   const renderQualifier = guard(getQualifierMessage(schema), (qualifier) => (
@@ -118,7 +126,12 @@ function ParamsItem({ param, ...rest }: Props) {
       if (typeof defaultValue === "string") {
         return (
           <div>
-            <strong>Default value: </strong>
+            <strong>
+              {translate({
+                id: OPENAPI_SCHEMA_ITEM.DEFAULT_VALUE,
+                message: "Default value:",
+              })}{" "}
+            </strong>
             <span>
               <code>{defaultValue}</code>
             </span>
@@ -127,7 +140,12 @@ function ParamsItem({ param, ...rest }: Props) {
       }
       return (
         <div>
-          <strong>Default value: </strong>
+          <strong>
+            {translate({
+              id: OPENAPI_SCHEMA_ITEM.DEFAULT_VALUE,
+              message: "Default value:",
+            })}{" "}
+          </strong>
           <span>
             <code>{JSON.stringify(defaultValue)}</code>
           </span>
@@ -137,40 +155,6 @@ function ParamsItem({ param, ...rest }: Props) {
     return undefined;
   }
 
-  const renderExample = guard(toString(example), (example) => (
-    <div>
-      <strong>Example: </strong>
-      {example}
-    </div>
-  ));
-
-  const renderExamples = guard(examples, (examples) => {
-    const exampleEntries = Object.entries(examples);
-    return (
-      <>
-        <strong>Examples:</strong>
-        <SchemaTabs>
-          {exampleEntries.map(([exampleName, exampleProperties]) => (
-            // @ts-ignore
-            <TabItem value={exampleName} label={exampleName}>
-              {exampleProperties.summary && <p>{exampleProperties.summary}</p>}
-              {exampleProperties.description && (
-                <p>
-                  <strong>Description: </strong>
-                  <span>{exampleProperties.description}</span>
-                </p>
-              )}
-              <p>
-                <strong>Example: </strong>
-                <code>{exampleProperties.value}</code>
-              </p>
-            </TabItem>
-          ))}
-        </SchemaTabs>
-      </>
-    );
-  });
-
   return (
     <div className="openapi-params__list-item">
       <span className="openapi-schema__container">
@@ -192,8 +176,8 @@ function ParamsItem({ param, ...rest }: Props) {
       {renderDescription}
       {renderEnumDescriptions}
       {renderDefaultValue()}
-      {renderExample}
-      {renderExamples}
+      <Example example={example} />
+      <Example examples={examples} />
     </div>
   );
 }

package/src/theme/RequestSchema/index.tsx

@@ -7,6 +7,9 @@
 
 import React from "react";
 
+import { translate } from "@docusaurus/Translate";
+import { OPENAPI_REQUEST, OPENAPI_SCHEMA_ITEM } from "@theme/translationIds";
+
 import BrowserOnly from "@docusaurus/BrowserOnly";
 import Details from "@theme/Details";
 import Markdown from "@theme/Markdown";
@@ -42,7 +45,7 @@ const RequestSchemaComponent: React.FC<Props> = ({ title, body, style }) => {
 
   if (mimeTypes.length > 1) {
     return (
-      <MimeTabs className="openapi-tabs__mime" schemaType="request">
+      <MimeTabs className="openapi-tabs__mime" schemaType="request" lazy>
         {mimeTypes.map((mimeType) => {
           const firstBody = body.content![mimeType].schema;
           if (
@@ -55,37 +58,49 @@ const RequestSchemaComponent: React.FC<Props> = ({ title, body, style }) => {
           return (
             // @ts-ignore
             <TabItem key={mimeType} label={mimeType} value={mimeType}>
-              <Details
-                className="openapi-markdown__details mime"
-                data-collapsed={false}
-                open={true}
-                style={style}
-                summary={
-                  <>
-                    <summary>
-                      <h3 className="openapi-markdown__details-summary-header-body">
-                        {title}
-                        {body.required === true && (
-                          <span className="openapi-schema__required">
-                            required
-                          </span>
-                        )}
-                      </h3>
-                    </summary>
-                  </>
-                }
-              >
-                <div style={{ textAlign: "left", marginLeft: "1rem" }}>
-                  {body.description && (
-                    <div style={{ marginTop: "1rem", marginBottom: "1rem" }}>
-                      <Markdown>{body.description}</Markdown>
-                    </div>
-                  )}
-                </div>
-                <ul style={{ marginLeft: "1rem" }}>
-                  <SchemaNode schema={firstBody} schemaType="request" />
-                </ul>
-              </Details>
+              <div style={{ marginTop: "1rem" }}>
+                <Details
+                  className="openapi-markdown__details mime"
+                  data-collapsed={false}
+                  open={true}
+                  style={style}
+                  summary={
+                    <>
+                      <summary>
+                        <h3 className="openapi-markdown__details-summary-header-body">
+                          {translate({
+                            id: OPENAPI_REQUEST.BODY_TITLE,
+                            message: title,
+                          })}
+                          {body.required === true && (
+                            <span className="openapi-schema__required">
+                              {translate({
+                                id: OPENAPI_SCHEMA_ITEM.REQUIRED,
+                                message: "required",
+                              })}
+                            </span>
+                          )}
+                        </h3>
+                      </summary>
+                    </>
+                  }
+                >
+                  <div style={{ textAlign: "left", marginLeft: "1rem" }}>
+                    {body.description && (
+                      <div style={{ marginTop: "1rem", marginBottom: "1rem" }}>
+                        <Markdown>{body.description}</Markdown>
+                      </div>
+                    )}
+                  </div>
+                  <ul style={{ marginLeft: "1rem" }}>
+                    <SchemaNode
+                      schema={firstBody}
+                      schemaType="request"
+                      schemaPath="requestBody"
+                    />
+                  </ul>
+                </Details>
+              </div>
             </TabItem>
           );
         })}
@@ -114,13 +129,19 @@ const RequestSchemaComponent: React.FC<Props> = ({ title, body, style }) => {
             <>
               <summary>
                 <h3 className="openapi-markdown__details-summary-header-body">
-                  {title}
+                  {translate({
+                    id: OPENAPI_REQUEST.BODY_TITLE,
+                    message: title,
+                  })}
                   {firstBody.type === "array" && (
                     <span style={{ opacity: "0.6" }}> array</span>
                   )}
                   {body.required && (
                     <strong className="openapi-schema__required">
-                      required
+                      {translate({
+                        id: OPENAPI_SCHEMA_ITEM.REQUIRED,
+                        message: "required",
+                      })}
                     </strong>
                   )}
                 </h3>
@@ -136,7 +157,11 @@ const RequestSchemaComponent: React.FC<Props> = ({ title, body, style }) => {
             )}
           </div>
           <ul style={{ marginLeft: "1rem" }}>
-            <SchemaNode schema={firstBody} schemaType="request" />
+            <SchemaNode
+              schema={firstBody}
+              schemaType="request"
+              schemaPath="requestBody"
+            />
           </ul>
         </Details>
       </TabItem>