docusaurus-theme-openapi-docs 4.5.0 → 4.6.0

package/lib/theme/Example/index.js

@@ -0,0 +1,170 @@
+"use strict";
+/* ============================================================================
+ * 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.
+ * ========================================================================== */
+var __importDefault =
+  (this && this.__importDefault) ||
+  function (mod) {
+    return mod && mod.__esModule ? mod : { default: mod };
+  };
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderExamplesRecord = exports.Example = void 0;
+exports.renderStringArrayExamples = renderStringArrayExamples;
+const react_1 = __importDefault(require("react"));
+const Translate_1 = require("@docusaurus/Translate");
+const SchemaTabs_1 = __importDefault(require("@theme/SchemaTabs"));
+const TabItem_1 = __importDefault(require("@theme/TabItem"));
+const translationIds_1 = require("@theme/translationIds");
+const EXAMPLE_CLASS_NAME = "openapi-example";
+const EXAMPLES_CLASS_NAME = "openapi-examples";
+/**
+ * Example Component
+ */
+const Example = ({ example, examples }) => {
+  if (example !== undefined) {
+    return renderExample(example);
+  }
+  if (examples !== undefined) {
+    return renderExamples(examples);
+  }
+  return undefined;
+};
+exports.Example = Example;
+/**
+ * Format example value
+ *
+ * @param example
+ * @returns
+ */
+const formatExample = (example) => {
+  if (typeof example === "object" && example !== null) {
+    return JSON.stringify(example);
+  }
+  return String(example);
+};
+const renderExample = (example) => {
+  return react_1.default.createElement(
+    "div",
+    { className: EXAMPLE_CLASS_NAME },
+    react_1.default.createElement(
+      "strong",
+      null,
+      (0, Translate_1.translate)({
+        id: translationIds_1.OPENAPI_SCHEMA_ITEM.EXAMPLE,
+        message: "Example:",
+      }),
+      " "
+    ),
+    react_1.default.createElement(
+      "span",
+      null,
+      react_1.default.createElement("code", null, formatExample(example))
+    )
+  );
+};
+const renderExamples = (examples) => {
+  if (Array.isArray(examples)) {
+    return renderStringArrayExamples(examples);
+  }
+  return (0, exports.renderExamplesRecord)(examples);
+};
+/**
+ * Render string examples
+ *
+ * @param examples
+ * @returns
+ */
+function renderStringArrayExamples(examples) {
+  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,
+      },
+    }),
+    {}
+  );
+  return (0, exports.renderExamplesRecord)(exampleEntries);
+}
+const renderExamplesRecord = (examples) => {
+  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 react_1.default.createElement(
+    "div",
+    { className: EXAMPLES_CLASS_NAME },
+    react_1.default.createElement(
+      "strong",
+      null,
+      (0, Translate_1.translate)({
+        id: translationIds_1.OPENAPI_SCHEMA_ITEM.EXAMPLES,
+        message: "Examples:",
+      })
+    ),
+    react_1.default.createElement(
+      SchemaTabs_1.default,
+      null,
+      exampleEntries.map(([exampleName, exampleProperties]) =>
+        renderExampleObject(exampleName, exampleProperties)
+      )
+    )
+  );
+};
+exports.renderExamplesRecord = renderExamplesRecord;
+/**
+ * Render example object
+ *
+ * @param exampleName
+ * @param exampleProperties
+ * @returns
+ */
+const renderExampleObject = (exampleName, exampleProperties) => {
+  return (
+    // @ts-ignore
+    react_1.default.createElement(
+      TabItem_1.default,
+      { value: exampleName, label: exampleName },
+      exampleProperties.summary &&
+        react_1.default.createElement("p", null, exampleProperties.summary),
+      exampleProperties.description &&
+        react_1.default.createElement(
+          "p",
+          null,
+          react_1.default.createElement(
+            "strong",
+            null,
+            (0, Translate_1.translate)({
+              id: translationIds_1.OPENAPI_SCHEMA_ITEM.DESCRIPTION,
+              message: "Description:",
+            }),
+            " "
+          ),
+          react_1.default.createElement(
+            "span",
+            null,
+            exampleProperties.description
+          )
+        ),
+      exampleProperties.value !== undefined
+        ? renderExample(exampleProperties.value)
+        : undefined
+    )
+  );
+};

package/lib/theme/ParamsDetails/index.js

@@ -12,6 +12,8 @@ var __importDefault =
   };
 Object.defineProperty(exports, "__esModule", { value: true });
 const react_1 = __importDefault(require("react"));
+const Translate_1 = require("@docusaurus/Translate");
+const translationIds_1 = require("@theme/translationIds");
 const BrowserOnly_1 = __importDefault(require("@docusaurus/BrowserOnly"));
 const Details_1 = __importDefault(require("@theme/Details"));
 const ParamsItem_1 = __importDefault(require("@theme/ParamsItem"));
@@ -32,7 +34,13 @@ const ParamsDetailsComponent = ({ parameters }) => {
         react_1.default.createElement(
           "h3",
           { className: "openapi-markdown__details-summary-header-params" },
-          `${type.charAt(0).toUpperCase() + type.slice(1)} Parameters`
+          (0, Translate_1.translate)(
+            {
+              id: translationIds_1.OPENAPI_PARAMS_DETAILS.PARAMETERS_TITLE,
+              message: "{type} Parameters",
+            },
+            { type: type.charAt(0).toUpperCase() + type.slice(1) }
+          )
         )
       );
       return react_1.default.createElement(

package/lib/theme/ParamsItem/index.d.ts

@@ -10,7 +10,7 @@ export interface Props {
     param: {
         description: string;
         example: any;
-        examples: Record<string, ExampleObject>;
+        examples: Record<string, ExampleObject> | undefined;
         name: string;
         required: boolean;
         deprecated: boolean;

package/lib/theme/ParamsItem/index.js

@@ -12,16 +12,25 @@ var __importDefault =
   };
 Object.defineProperty(exports, "__esModule", { value: true });
 const react_1 = __importDefault(require("react"));
+const Translate_1 = require("@docusaurus/Translate");
+const Example_1 = require("@theme/Example");
 const Markdown_1 = __importDefault(require("@theme/Markdown"));
-const SchemaTabs_1 = __importDefault(require("@theme/SchemaTabs"));
-const TabItem_1 = __importDefault(require("@theme/TabItem"));
 /* eslint-disable import/no-extraneous-dependencies*/
+const translationIds_1 = require("@theme/translationIds");
 const clsx_1 = __importDefault(require("clsx"));
 const schema_1 = require("../../markdown/schema");
 const utils_1 = require("../../markdown/utils");
 const getEnumDescriptionMarkdown = (enumDescriptions) => {
   if (enumDescriptions?.length) {
-    return `| Enum Value | Description |
+    const enumValue = (0, Translate_1.translate)({
+      id: translationIds_1.OPENAPI_SCHEMA_ITEM.ENUM_VALUE,
+      message: "Enum Value",
+    });
+    const description = (0, Translate_1.translate)({
+      id: translationIds_1.OPENAPI_SCHEMA_ITEM.ENUM_DESCRIPTION,
+      message: "Description",
+    });
+    return `| ${enumValue} | ${description} |
 | ---- | ----- |
 ${enumDescriptions
   .map((desc) => {
@@ -33,17 +42,11 @@ ${enumDescriptions
   return "";
 };
 function ParamsItem({ param, ...rest }) {
-  const {
-    description,
-    example,
-    examples,
-    name,
-    required,
-    deprecated,
-    enumDescriptions,
-  } = param;
+  const { description, name, required, deprecated, enumDescriptions } = param;
   let schema = param.schema;
   let defaultValue;
+  let examples = param.examples ?? schema?.examples;
+  let example = param.example ?? schema?.example;
   if (!schema) {
     schema = { type: "any" };
   }
@@ -69,14 +72,20 @@ function ParamsItem({ param, ...rest }) {
     react_1.default.createElement(
       "span",
       { className: "openapi-schema__required" },
-      "required"
+      (0, Translate_1.translate)({
+        id: translationIds_1.OPENAPI_SCHEMA_ITEM.REQUIRED,
+        message: "required",
+      })
     )
   );
   const renderDeprecated = (0, utils_1.guard)(deprecated, () =>
     react_1.default.createElement(
       "span",
       { className: "openapi-schema__deprecated" },
-      "deprecated"
+      (0, Translate_1.translate)({
+        id: translationIds_1.OPENAPI_SCHEMA_ITEM.DEPRECATED,
+        message: "deprecated",
+      })
     )
   );
   const renderQualifier = (0, utils_1.guard)(
@@ -103,7 +112,15 @@ function ParamsItem({ param, ...rest }) {
         return react_1.default.createElement(
           "div",
           null,
-          react_1.default.createElement("strong", null, "Default value: "),
+          react_1.default.createElement(
+            "strong",
+            null,
+            (0, Translate_1.translate)({
+              id: translationIds_1.OPENAPI_SCHEMA_ITEM.DEFAULT_VALUE,
+              message: "Default value:",
+            }),
+            " "
+          ),
           react_1.default.createElement(
             "span",
             null,
@@ -114,7 +131,15 @@ function ParamsItem({ param, ...rest }) {
       return react_1.default.createElement(
         "div",
         null,
-        react_1.default.createElement("strong", null, "Default value: "),
+        react_1.default.createElement(
+          "strong",
+          null,
+          (0, Translate_1.translate)({
+            id: translationIds_1.OPENAPI_SCHEMA_ITEM.DEFAULT_VALUE,
+            message: "Default value:",
+          }),
+          " "
+        ),
         react_1.default.createElement(
           "span",
           null,
@@ -128,62 +153,6 @@ function ParamsItem({ param, ...rest }) {
     }
     return undefined;
   }
-  const renderExample = (0, utils_1.guard)(
-    (0, utils_1.toString)(example),
-    (example) =>
-      react_1.default.createElement(
-        "div",
-        null,
-        react_1.default.createElement("strong", null, "Example: "),
-        example
-      )
-  );
-  const renderExamples = (0, utils_1.guard)(examples, (examples) => {
-    const exampleEntries = Object.entries(examples);
-    return react_1.default.createElement(
-      react_1.default.Fragment,
-      null,
-      react_1.default.createElement("strong", null, "Examples:"),
-      react_1.default.createElement(
-        SchemaTabs_1.default,
-        null,
-        exampleEntries.map(([exampleName, exampleProperties]) =>
-          // @ts-ignore
-          react_1.default.createElement(
-            TabItem_1.default,
-            { value: exampleName, label: exampleName },
-            exampleProperties.summary &&
-              react_1.default.createElement(
-                "p",
-                null,
-                exampleProperties.summary
-              ),
-            exampleProperties.description &&
-              react_1.default.createElement(
-                "p",
-                null,
-                react_1.default.createElement("strong", null, "Description: "),
-                react_1.default.createElement(
-                  "span",
-                  null,
-                  exampleProperties.description
-                )
-              ),
-            react_1.default.createElement(
-              "p",
-              null,
-              react_1.default.createElement("strong", null, "Example: "),
-              react_1.default.createElement(
-                "code",
-                null,
-                exampleProperties.value
-              )
-            )
-          )
-        )
-      )
-    );
-  });
   return react_1.default.createElement(
     "div",
     { className: "openapi-params__list-item" },
@@ -211,8 +180,8 @@ function ParamsItem({ param, ...rest }) {
     renderDescription,
     renderEnumDescriptions,
     renderDefaultValue(),
-    renderExample,
-    renderExamples
+    react_1.default.createElement(Example_1.Example, { example: example }),
+    react_1.default.createElement(Example_1.Example, { examples: examples })
   );
 }
 exports.default = ParamsItem;

package/lib/theme/RequestSchema/index.js

@@ -12,6 +12,8 @@ var __importDefault =
   };
 Object.defineProperty(exports, "__esModule", { value: true });
 const react_1 = __importDefault(require("react"));
+const Translate_1 = require("@docusaurus/Translate");
+const translationIds_1 = require("@theme/translationIds");
 const BrowserOnly_1 = __importDefault(require("@docusaurus/BrowserOnly"));
 const Details_1 = __importDefault(require("@theme/Details"));
 const Markdown_1 = __importDefault(require("@theme/Markdown"));
@@ -66,12 +68,18 @@ const RequestSchemaComponent = ({ title, body, style }) => {
                         className:
                           "openapi-markdown__details-summary-header-body",
                       },
-                      title,
+                      (0, Translate_1.translate)({
+                        id: translationIds_1.OPENAPI_REQUEST.BODY_TITLE,
+                        message: title,
+                      }),
                       body.required === true &&
                         react_1.default.createElement(
                           "span",
                           { className: "openapi-schema__required" },
-                          "required"
+                          (0, Translate_1.translate)({
+                            id: translationIds_1.OPENAPI_SCHEMA_ITEM.REQUIRED,
+                            message: "required",
+                          })
                         )
                     )
                   )
@@ -133,7 +141,10 @@ const RequestSchemaComponent = ({ title, body, style }) => {
               react_1.default.createElement(
                 "h3",
                 { className: "openapi-markdown__details-summary-header-body" },
-                title,
+                (0, Translate_1.translate)({
+                  id: translationIds_1.OPENAPI_REQUEST.BODY_TITLE,
+                  message: title,
+                }),
                 firstBody.type === "array" &&
                   react_1.default.createElement(
                     "span",
@@ -144,7 +155,10 @@ const RequestSchemaComponent = ({ title, body, style }) => {
                   react_1.default.createElement(
                     "strong",
                     { className: "openapi-schema__required" },
-                    "required"
+                    (0, Translate_1.translate)({
+                      id: translationIds_1.OPENAPI_SCHEMA_ITEM.REQUIRED,
+                      message: "required",
+                    })
                   )
               )
             )

package/lib/theme/ResponseExamples/index.js

@@ -17,9 +17,11 @@ exports.ExampleFromSchema =
     void 0;
 exports.json2xml = json2xml;
 const react_1 = __importDefault(require("react"));
+const Translate_1 = require("@docusaurus/Translate");
 const CodeSamples_1 = __importDefault(require("@theme/CodeSamples"));
 const Markdown_1 = __importDefault(require("@theme/Markdown"));
 const TabItem_1 = __importDefault(require("@theme/TabItem"));
+const translationIds_1 = require("@theme/translationIds");
 const createResponseExample_1 = require("docusaurus-plugin-openapi-docs/lib/openapi/createResponseExample");
 const xml_formatter_1 = __importDefault(require("xml-formatter"));
 function json2xml(o, tab) {
@@ -107,7 +109,13 @@ const ResponseExample = ({ responseExample, mimeType }) => {
     // @ts-ignore
     react_1.default.createElement(
       TabItem_1.default,
-      { label: "Example", value: "Example" },
+      {
+        label: (0, Translate_1.translate)({
+          id: translationIds_1.OPENAPI_RESPONSE_EXAMPLES.EXAMPLE,
+          message: "Example",
+        }),
+        value: "Example",
+      },
       responseExample.summary &&
         react_1.default.createElement(
           Markdown_1.default,
@@ -163,7 +171,13 @@ const ExampleFromSchema = ({ schema, mimeType }) => {
         // @ts-ignore
         react_1.default.createElement(
           TabItem_1.default,
-          { label: "Example (auto)", value: "Example (auto)" },
+          {
+            label: (0, Translate_1.translate)({
+              id: translationIds_1.OPENAPI_RESPONSE_EXAMPLES.AUTO_EXAMPLE,
+              message: "Example (auto)",
+            }),
+            value: "Example (auto)",
+          },
           react_1.default.createElement(CodeSamples_1.default, {
             example: xmlExample,
             language: "xml",
@@ -180,7 +194,13 @@ const ExampleFromSchema = ({ schema, mimeType }) => {
       // @ts-ignore
       react_1.default.createElement(
         TabItem_1.default,
-        { label: "Example (auto)", value: "Example (auto)" },
+        {
+          label: (0, Translate_1.translate)({
+            id: translationIds_1.OPENAPI_RESPONSE_EXAMPLES.AUTO_EXAMPLE,
+            message: "Example (auto)",
+          }),
+          value: "Example (auto)",
+        },
         react_1.default.createElement(CodeSamples_1.default, {
           example: JSON.stringify(responseExample, null, 2),
           language: "json",