docusaurus-theme-openapi-docs 0.0.0-1079 → 0.0.0-1081

package/lib/markdown/schema.js

@@ -37,6 +37,9 @@ function prettyName(schema, circular) {
         return schema.xml?.name ?? schema.type;
         // return schema.type;
     }
+    if (Array.isArray(schema.type)) {
+        return schema.type.join(" | ");
+    }
     return schema.title ?? schema.type;
 }
 function getSchemaName(schema, circular) {

package/lib/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/lib/theme/Example/index.d.ts

@@ -0,0 +1,24 @@
+import React from "react";
+import { ExampleObject } from "@theme/ParamsItem";
+type ExampleType = string;
+type ExamplesType = Record<string, ExampleObject> | string[];
+/**
+ * Example Component Props
+ */
+type ExampleProps = {
+    example?: ExampleType;
+    examples?: ExamplesType;
+};
+/**
+ * Example Component
+ */
+export declare const Example: ({ example, examples }: ExampleProps) => React.JSX.Element | undefined;
+/**
+ * Render string examples
+ *
+ * @param examples
+ * @returns
+ */
+export declare function renderStringArrayExamples(examples: string[]): React.JSX.Element | undefined;
+export declare const renderExamplesRecord: (examples: Record<string, ExampleObject>) => React.JSX.Element | undefined;
+export {};

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

@@ -13,12 +13,11 @@ 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 clsx_1 = __importDefault(require("clsx"));
 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) => {
@@ -43,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" };
   }
@@ -160,93 +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,
-          (0, Translate_1.translate)({
-            id: translationIds_1.OPENAPI_SCHEMA_ITEM.EXAMPLE,
-            message: "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,
-        (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]) =>
-          // @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
-                )
-              ),
-            react_1.default.createElement(
-              "p",
-              null,
-              react_1.default.createElement(
-                "strong",
-                null,
-                (0, Translate_1.translate)({
-                  id: translationIds_1.OPENAPI_SCHEMA_ITEM.EXAMPLE,
-                  message: "Example:",
-                }),
-                " "
-              ),
-              react_1.default.createElement(
-                "code",
-                null,
-                exampleProperties.value
-              )
-            )
-          )
-        )
-      )
-    );
-  });
   return react_1.default.createElement(
     "div",
     { className: "openapi-params__list-item" },
@@ -274,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/ResponseSchema/index.js

@@ -12,9 +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 Translate_1 = require("@docusaurus/Translate");
 const Details_1 = __importDefault(require("@theme/Details"));
 const Markdown_1 = __importDefault(require("@theme/Markdown"));
 const MimeTabs_1 = __importDefault(require("@theme/MimeTabs")); // Assume these components exist
@@ -23,6 +22,7 @@ const Schema_1 = __importDefault(require("@theme/Schema"));
 const SchemaTabs_1 = __importDefault(require("@theme/SchemaTabs"));
 const SkeletonLoader_1 = __importDefault(require("@theme/SkeletonLoader"));
 const TabItem_1 = __importDefault(require("@theme/TabItem"));
+const translationIds_1 = require("@theme/translationIds");
 const ResponseSchemaComponent = ({ title, body, style }) => {
   if (
     body === undefined ||
@@ -39,109 +39,118 @@ const ResponseSchemaComponent = ({ title, body, style }) => {
       MimeTabs_1.default,
       { className: "openapi-tabs__mime", schemaType: "response" },
       mimeTypes.map((mimeType) => {
-        const responseExamples = body.content[mimeType].examples;
-        const responseExample = body.content[mimeType].example;
-        const firstBody =
-          body.content[mimeType].schema ?? body.content[mimeType];
+        const mediaTypeObject = body.content?.[mimeType];
+        const responseExamples = mediaTypeObject?.examples;
+        const responseExample = mediaTypeObject?.example;
+        const firstBody = mediaTypeObject?.schema;
         if (
-          firstBody === undefined &&
-          responseExample === undefined &&
-          responseExamples === undefined
+          !firstBody ||
+          (firstBody.properties &&
+            Object.keys(firstBody.properties).length === 0)
         ) {
-          return undefined;
-        }
-        if (firstBody) {
           return (
             // @ts-ignore
             react_1.default.createElement(
               TabItem_1.default,
               { key: mimeType, label: mimeType, value: mimeType },
               react_1.default.createElement(
-                SchemaTabs_1.default,
-                { className: "openapi-tabs__schema" },
+                "div",
+                null,
+                (0, Translate_1.translate)({
+                  id: translationIds_1.OPENAPI_SCHEMA.NO_SCHEMA,
+                  message: "No schema",
+                })
+              )
+            )
+          );
+        }
+        return (
+          // @ts-ignore
+          react_1.default.createElement(
+            TabItem_1.default,
+            { key: mimeType, label: mimeType, value: mimeType },
+            react_1.default.createElement(
+              SchemaTabs_1.default,
+              { className: "openapi-tabs__schema" },
+              react_1.default.createElement(
+                TabItem_1.default,
+                { key: title, label: title, value: title },
                 react_1.default.createElement(
-                  TabItem_1.default,
-                  { key: title, label: title, value: title },
-                  react_1.default.createElement(
-                    Details_1.default,
-                    {
-                      className: "openapi-markdown__details response",
-                      "data-collapsed": false,
-                      open: true,
-                      style: style,
-                      summary: react_1.default.createElement(
-                        react_1.default.Fragment,
+                  Details_1.default,
+                  {
+                    className: "openapi-markdown__details response",
+                    "data-collapsed": false,
+                    open: true,
+                    style: style,
+                    summary: react_1.default.createElement(
+                      react_1.default.Fragment,
+                      null,
+                      react_1.default.createElement(
+                        "summary",
                         null,
                         react_1.default.createElement(
-                          "summary",
-                          null,
-                          react_1.default.createElement(
-                            "strong",
-                            {
-                              className:
-                                "openapi-markdown__details-summary-response",
-                            },
-                            title,
-                            body.required === true &&
-                              react_1.default.createElement(
-                                "span",
-                                { className: "openapi-schema__required" },
-                                (0, Translate_1.translate)({
-                                  id: translationIds_1.OPENAPI_SCHEMA_ITEM
-                                    .REQUIRED,
-                                  message: "required",
-                                })
-                              )
-                          )
-                        )
-                      ),
-                    },
-                    react_1.default.createElement(
-                      "div",
-                      { style: { textAlign: "left", marginLeft: "1rem" } },
-                      body.description &&
-                        react_1.default.createElement(
-                          "div",
+                          "strong",
                           {
-                            style: { marginTop: "1rem", marginBottom: "1rem" },
+                            className:
+                              "openapi-markdown__details-summary-response",
                           },
-                          react_1.default.createElement(
-                            Markdown_1.default,
-                            null,
-                            body.description
-                          )
+                          title,
+                          body.required === true &&
+                            react_1.default.createElement(
+                              "span",
+                              { className: "openapi-schema__required" },
+                              (0, Translate_1.translate)({
+                                id: translationIds_1.OPENAPI_SCHEMA_ITEM
+                                  .REQUIRED,
+                                message: "required",
+                              })
+                            )
                         )
+                      )
                     ),
-                    react_1.default.createElement(
-                      "ul",
-                      { style: { marginLeft: "1rem" } },
-                      react_1.default.createElement(Schema_1.default, {
-                        schema: firstBody,
-                        schemaType: "response",
-                      })
-                    )
+                  },
+                  react_1.default.createElement(
+                    "div",
+                    { style: { textAlign: "left", marginLeft: "1rem" } },
+                    body.description &&
+                      react_1.default.createElement(
+                        "div",
+                        { style: { marginTop: "1rem", marginBottom: "1rem" } },
+                        react_1.default.createElement(
+                          Markdown_1.default,
+                          null,
+                          body.description
+                        )
+                      )
+                  ),
+                  react_1.default.createElement(
+                    "ul",
+                    { style: { marginLeft: "1rem" } },
+                    react_1.default.createElement(Schema_1.default, {
+                      schema: firstBody,
+                      schemaType: "response",
+                    })
                   )
-                ),
-                firstBody &&
-                  (0, ResponseExamples_1.ExampleFromSchema)({
-                    schema: firstBody,
-                    mimeType: mimeType,
-                  }),
-                responseExamples &&
-                  (0, ResponseExamples_1.ResponseExamples)({
-                    responseExamples,
-                    mimeType,
-                  }),
-                responseExample &&
-                  (0, ResponseExamples_1.ResponseExample)({
-                    responseExample,
-                    mimeType,
-                  })
-              )
+                )
+              ),
+              firstBody &&
+                (0, ResponseExamples_1.ExampleFromSchema)({
+                  schema: firstBody,
+                  mimeType: mimeType,
+                }),
+              responseExamples &&
+                (0, ResponseExamples_1.ResponseExamples)({
+                  responseExamples,
+                  mimeType,
+                }),
+              responseExample &&
+                (0, ResponseExamples_1.ResponseExample)({
+                  responseExample,
+                  mimeType,
+                })
             )
-          );
-        }
-        return undefined;
+          )
+        );
       })
     );
   }

package/lib/theme/SchemaItem/index.js

@@ -13,10 +13,11 @@ var __importDefault =
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.default = SchemaItem;
 const react_1 = __importDefault(require("react"));
-const Markdown_1 = __importDefault(require("@theme/Markdown"));
-const clsx_1 = __importDefault(require("clsx"));
 const Translate_1 = require("@docusaurus/Translate");
+const Example_1 = require("@theme/Example");
+const Markdown_1 = __importDefault(require("@theme/Markdown"));
 const translationIds_1 = require("@theme/translationIds");
+const clsx_1 = __importDefault(require("clsx"));
 const utils_1 = require("../../markdown/utils");
 const transformEnumDescriptions = (enumDescriptions) => {
   if (enumDescriptions) {
@@ -59,6 +60,7 @@ function SchemaItem(props) {
   let schemaDescription;
   let defaultValue;
   let example;
+  let examples;
   let nullable;
   let enumDescriptions = [];
   let constValue;
@@ -68,6 +70,7 @@ function SchemaItem(props) {
     enumDescriptions = transformEnumDescriptions(schema["x-enumDescriptions"]);
     defaultValue = schema.default;
     example = schema.example;
+    examples = schema.examples;
     nullable =
       schema.nullable ||
       (Array.isArray(schema.type) && schema.type.includes("null")); // support JSON Schema nullable
@@ -180,49 +183,6 @@ function SchemaItem(props) {
     }
     return undefined;
   }
-  function renderExample() {
-    if (example !== undefined) {
-      if (typeof example === "string") {
-        return react_1.default.createElement(
-          "div",
-          null,
-          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, example)
-          )
-        );
-      }
-      return react_1.default.createElement(
-        "div",
-        null,
-        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, JSON.stringify(example))
-        )
-      );
-    }
-    return undefined;
-  }
   function renderConstValue() {
     if (constValue !== undefined) {
       if (typeof constValue === "string") {
@@ -303,7 +263,8 @@ function SchemaItem(props) {
     renderQualifierMessage,
     renderConstValue(),
     renderDefaultValue(),
-    renderExample(),
+    react_1.default.createElement(Example_1.Example, { example: example }),
+    react_1.default.createElement(Example_1.Example, { examples: examples }),
     collapsibleSchemaContent ?? collapsibleSchemaContent
   );
   return react_1.default.createElement(

package/lib/theme/styles.scss

@@ -41,6 +41,8 @@
 @use "./CodeSamples/CodeSamples";
 /* Markdown Styling */
 @use "./Markdown/Details/Details";
+/* Example Styling */
+@use "./Example/Example";
 
 :root {
   --openapi-required: var(--ifm-color-danger);