docusaurus-theme-openapi-docs 4.0.1 → 4.2.0

package/lib/theme/ApiItem/Layout/index.js

@@ -0,0 +1,121 @@
+"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 });
+const react_1 = __importDefault(require("react"));
+const client_1 = require("@docusaurus/plugin-content-docs/client");
+const theme_common_1 = require("@docusaurus/theme-common");
+const ContentVisibility_1 = __importDefault(
+  require("@theme/ContentVisibility")
+);
+const DocBreadcrumbs_1 = __importDefault(require("@theme/DocBreadcrumbs"));
+const Content_1 = __importDefault(require("@theme/DocItem/Content"));
+const Footer_1 = __importDefault(require("@theme/DocItem/Footer"));
+const Paginator_1 = __importDefault(require("@theme/DocItem/Paginator"));
+const Desktop_1 = __importDefault(require("@theme/DocItem/TOC/Desktop"));
+const Mobile_1 = __importDefault(require("@theme/DocItem/TOC/Mobile"));
+const DocVersionBadge_1 = __importDefault(require("@theme/DocVersionBadge"));
+const DocVersionBanner_1 = __importDefault(require("@theme/DocVersionBanner"));
+const clsx_1 = __importDefault(require("clsx"));
+const styles_module_css_1 = __importDefault(require("./styles.module.css"));
+/**
+ * Decide if the toc should be rendered, on mobile or desktop viewports
+ */
+function useDocTOC() {
+  const { frontMatter, toc } = (0, client_1.useDoc)();
+  const windowSize = (0, theme_common_1.useWindowSize)();
+  const hidden = frontMatter.hide_table_of_contents;
+  const canRender = !hidden && toc.length > 0;
+  const mobile = canRender
+    ? react_1.default.createElement(Mobile_1.default, null)
+    : undefined;
+  const desktop =
+    canRender && (windowSize === "desktop" || windowSize === "ssr")
+      ? react_1.default.createElement(Desktop_1.default, null)
+      : undefined;
+  return {
+    hidden,
+    mobile,
+    desktop,
+  };
+}
+function DocItemLayout({ children }) {
+  const docTOC = useDocTOC();
+  const { metadata } = (0, client_1.useDoc)();
+  const { frontMatter } = (0, client_1.useDoc)();
+  const api = frontMatter.api;
+  const schema = frontMatter.schema;
+  return react_1.default.createElement(
+    "div",
+    { className: "row" },
+    react_1.default.createElement(
+      "div",
+      {
+        className: (0, clsx_1.default)(
+          "col",
+          !docTOC.hidden && styles_module_css_1.default.docItemCol
+        ),
+      },
+      react_1.default.createElement(ContentVisibility_1.default, {
+        metadata: metadata,
+      }),
+      react_1.default.createElement(DocVersionBanner_1.default, null),
+      react_1.default.createElement(
+        "div",
+        { className: styles_module_css_1.default.docItemContainer },
+        react_1.default.createElement(
+          "article",
+          null,
+          react_1.default.createElement(DocBreadcrumbs_1.default, null),
+          react_1.default.createElement(DocVersionBadge_1.default, null),
+          docTOC.mobile,
+          react_1.default.createElement(Content_1.default, null, children),
+          react_1.default.createElement(
+            "div",
+            { className: "row" },
+            react_1.default.createElement(
+              "div",
+              {
+                className: (0, clsx_1.default)(
+                  "col",
+                  api || schema ? "col--7" : "col--12"
+                ),
+              },
+              react_1.default.createElement(Footer_1.default, null)
+            )
+          )
+        ),
+        react_1.default.createElement(
+          "div",
+          { className: "row" },
+          react_1.default.createElement(
+            "div",
+            {
+              className: (0, clsx_1.default)(
+                "col",
+                api || schema ? "col--7" : "col--12"
+              ),
+            },
+            react_1.default.createElement(Paginator_1.default, null)
+          )
+        )
+      )
+    ),
+    docTOC.desktop &&
+      react_1.default.createElement(
+        "div",
+        { className: "col col--3" },
+        docTOC.desktop
+      )
+  );
+}
+exports.default = DocItemLayout;

package/lib/theme/ApiItem/Layout/styles.module.css

@@ -0,0 +1,17 @@
+/* ============================================================================
+ * 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.
+ * ========================================================================== */
+
+.docItemContainer header + *,
+.docItemContainer article > *:first-child {
+  margin-top: 0;
+}
+
+@media (min-width: 997px) {
+  .docItemCol {
+    max-width: 75% !important;
+  }
+}

package/lib/theme/ApiItem/index.js

@@ -25,8 +25,10 @@ const useDocusaurusContext_1 = __importDefault(
 const useIsBrowser_1 = __importDefault(require("@docusaurus/useIsBrowser"));
 const slice_1 = require("@theme/ApiExplorer/Authorization/slice");
 const persistanceMiddleware_1 = require("@theme/ApiExplorer/persistanceMiddleware");
-const Layout_1 = __importDefault(require("@theme/DocItem/Layout"));
+const Layout_1 = __importDefault(require("@theme/ApiItem/Layout"));
+const CodeBlock_1 = __importDefault(require("@theme/CodeBlock"));
 const Metadata_1 = __importDefault(require("@theme/DocItem/Metadata"));
+const SkeletonLoader_1 = __importDefault(require("@theme/SkeletonLoader"));
 const clsx_1 = __importDefault(require("clsx"));
 const react_redux_1 = require("react-redux");
 const store_1 = require("./store");
@@ -42,6 +44,7 @@ function ApiItem(props) {
   const { info_path: infoPath } = frontMatter;
   let { api } = frontMatter;
   const { schema } = frontMatter;
+  const { sample } = frontMatter;
   // decompress and parse
   if (api) {
     try {
@@ -149,9 +152,8 @@ function ApiItem(props) {
                   BrowserOnly_1.default,
                   {
                     fallback: react_1.default.createElement(
-                      "div",
-                      null,
-                      "Loading..."
+                      SkeletonLoader_1.default,
+                      { size: "lg" }
                     ),
                   },
                   () => {
@@ -183,8 +185,17 @@ function ApiItem(props) {
             { className: (0, clsx_1.default)("row", "theme-api-markdown") },
             react_1.default.createElement(
               "div",
-              { className: "col col--12" },
+              { className: "col col--7 openapi-left-panel__container schema" },
               react_1.default.createElement(MDXComponent, null)
+            ),
+            react_1.default.createElement(
+              "div",
+              { className: "col col--5 openapi-right-panel__container" },
+              react_1.default.createElement(
+                CodeBlock_1.default,
+                { language: "json", title: `${frontMatter.title}` },
+                JSON.stringify(sample, null, 2)
+              )
             )
           )
         )

package/lib/theme/ApiTabs/_ApiTabs.scss

@@ -6,7 +6,6 @@
  * ========================================================================== */
 .openapi-tabs__container {
   margin-left: -1px;
-  margin-bottom: var(--ifm-leading);
 }
 
 .openapi-tabs__response-header {

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

@@ -0,0 +1,3 @@
+import React from "react";
+export declare const OpeningArrayBracket: () => React.JSX.Element;
+export declare const ClosingArrayBracket: () => React.JSX.Element;

package/lib/theme/ArrayBrackets/index.js

@@ -0,0 +1,50 @@
+"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.ClosingArrayBracket = exports.OpeningArrayBracket = void 0;
+const react_1 = __importDefault(require("react"));
+const OpeningArrayBracket = () =>
+  react_1.default.createElement(
+    "li",
+    null,
+    react_1.default.createElement(
+      "div",
+      {
+        style: {
+          fontSize: "var(--ifm-code-font-size)",
+          opacity: 0.6,
+          marginLeft: "-.5rem",
+          paddingBottom: ".5rem",
+        },
+      },
+      "Array ["
+    )
+  );
+exports.OpeningArrayBracket = OpeningArrayBracket;
+const ClosingArrayBracket = () =>
+  react_1.default.createElement(
+    "li",
+    null,
+    react_1.default.createElement(
+      "div",
+      {
+        style: {
+          fontSize: "var(--ifm-code-font-size)",
+          opacity: 0.6,
+          marginLeft: "-.5rem",
+        },
+      },
+      "]"
+    )
+  );
+exports.ClosingArrayBracket = ClosingArrayBracket;

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

@@ -0,0 +1,6 @@
+import React from "react";
+interface Props {
+    parameters: any[];
+}
+declare const ParamsDetails: React.FC<Props>;
+export default ParamsDetails;

package/lib/theme/ParamsDetails/index.js

@@ -0,0 +1,134 @@
+"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 __createBinding =
+  (this && this.__createBinding) ||
+  (Object.create
+    ? function (o, m, k, k2) {
+        if (k2 === undefined) k2 = k;
+        var desc = Object.getOwnPropertyDescriptor(m, k);
+        if (
+          !desc ||
+          ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)
+        ) {
+          desc = {
+            enumerable: true,
+            get: function () {
+              return m[k];
+            },
+          };
+        }
+        Object.defineProperty(o, k2, desc);
+      }
+    : function (o, m, k, k2) {
+        if (k2 === undefined) k2 = k;
+        o[k2] = m[k];
+      });
+var __setModuleDefault =
+  (this && this.__setModuleDefault) ||
+  (Object.create
+    ? function (o, v) {
+        Object.defineProperty(o, "default", { enumerable: true, value: v });
+      }
+    : function (o, v) {
+        o["default"] = v;
+      });
+var __importStar =
+  (this && this.__importStar) ||
+  function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null)
+      for (var k in mod)
+        if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k))
+          __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+  };
+var __importDefault =
+  (this && this.__importDefault) ||
+  function (mod) {
+    return mod && mod.__esModule ? mod : { default: mod };
+  };
+Object.defineProperty(exports, "__esModule", { value: true });
+const react_1 = __importStar(require("react"));
+const BrowserOnly_1 = __importDefault(require("@docusaurus/BrowserOnly"));
+const Details_1 = __importDefault(require("@theme/Details"));
+const ParamsItem_1 = __importDefault(require("@theme/ParamsItem"));
+const SkeletonLoader_1 = __importDefault(require("@theme/SkeletonLoader"));
+const ParamsDetailsComponent = ({ parameters }) => {
+  const types = ["path", "query", "header", "cookie"];
+  return react_1.default.createElement(
+    react_1.default.Fragment,
+    null,
+    types.map((type) => {
+      const params = parameters?.filter((param) => param?.in === type);
+      if (!params || params.length === 0) {
+        return null;
+      }
+      const summaryElement = react_1.default.createElement(
+        "summary",
+        null,
+        react_1.default.createElement(
+          "h3",
+          { className: "openapi-markdown__details-summary-header-params" },
+          `${type.charAt(0).toUpperCase() + type.slice(1)} Parameters`
+        )
+      );
+      return react_1.default.createElement(
+        Details_1.default,
+        {
+          key: type,
+          className: "openapi-markdown__details",
+          style: { marginBottom: "1rem" },
+          "data-collapsed": false,
+          open: true,
+          summary: summaryElement,
+        },
+        react_1.default.createElement(
+          "ul",
+          null,
+          params.map((param, index) =>
+            react_1.default.createElement(ParamsItem_1.default, {
+              key: index,
+              className: "paramsItem",
+              param: {
+                ...param,
+                enumDescriptions: Object.entries(
+                  param?.schema?.["x-enumDescriptions"] ??
+                    param?.schema?.items?.["x-enumDescriptions"] ??
+                    {}
+                ),
+              },
+            })
+          )
+        )
+      );
+    })
+  );
+};
+const ParamsDetails = (props) => {
+  return react_1.default.createElement(
+    BrowserOnly_1.default,
+    {
+      fallback: react_1.default.createElement(SkeletonLoader_1.default, {
+        size: "sm",
+      }),
+    },
+    () => {
+      const LazyComponent = react_1.default.lazy(() =>
+        Promise.resolve({ default: ParamsDetailsComponent })
+      );
+      return react_1.default.createElement(
+        react_1.Suspense,
+        { fallback: null },
+        react_1.default.createElement(LazyComponent, { ...props })
+      );
+    }
+  );
+};
+exports.default = ParamsDetails;

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

@@ -9,6 +9,7 @@ export interface ExampleObject {
     externalValue?: string;
 }
 export interface Props {
+    className: string;
     param: {
         description: string;
         example: any;
@@ -17,7 +18,8 @@ export interface Props {
         required: boolean;
         deprecated: boolean;
         schema: any;
+        enumDescriptions?: [string, string][];
     };
 }
-declare function ParamsItem({ param: { description, example, examples, name, required, schema, deprecated }, }: Props): React.JSX.Element;
+declare function ParamsItem({ param, ...rest }: Props): React.JSX.Element;
 export default ParamsItem;

package/lib/theme/ParamsItem/index.js

@@ -19,15 +19,45 @@ const TabItem_1 = __importDefault(require("@theme/TabItem"));
 const clsx_1 = __importDefault(require("clsx"));
 const react_markdown_1 = __importDefault(require("react-markdown"));
 const rehype_raw_1 = __importDefault(require("rehype-raw"));
+const remark_gfm_1 = __importDefault(require("remark-gfm"));
 const createDescription_1 = require("../../markdown/createDescription");
 const schema_1 = require("../../markdown/schema");
 const utils_1 = require("../../markdown/utils");
-function ParamsItem({
-  param: { description, example, examples, name, required, schema, deprecated },
-}) {
+const getEnumDescriptionMarkdown = (enumDescriptions) => {
+  if (enumDescriptions?.length) {
+    return `| Enum Value | Description |
+| ---- | ----- |
+${enumDescriptions
+  .map((desc) => {
+    return `| ${desc[0]} | ${desc[1]} | `.replaceAll("\n", "<br/>");
+  })
+  .join("\n")}
+    `;
+  }
+  return "";
+};
+function ParamsItem({ param, ...rest }) {
+  const {
+    description,
+    example,
+    examples,
+    name,
+    required,
+    deprecated,
+    enumDescriptions,
+  } = param;
+  let schema = param.schema;
+  let defaultValue;
   if (!schema || !schema?.type) {
     schema = { type: "any" };
   }
+  if (schema) {
+    if (schema.items) {
+      defaultValue = schema.items.default;
+    } else {
+      defaultValue = schema.default;
+    }
+  }
   const renderSchemaName = (0, utils_1.guard)(schema, (schema) =>
     react_1.default.createElement(
       "span",
@@ -64,7 +94,7 @@ function ParamsItem({
   );
   const renderDescription = (0, utils_1.guard)(description, (description) =>
     react_1.default.createElement(
-      "div",
+      react_1.default.Fragment,
       null,
       react_1.default.createElement(react_markdown_1.default, {
         children: (0, createDescription_1.createDescription)(description),
@@ -91,21 +121,51 @@ function ParamsItem({
       })
     )
   );
-  const renderDefaultValue = (0, utils_1.guard)(
-    schema && schema.items
-      ? schema.items.default
-      : schema
-        ? schema.default
-        : undefined,
-    (value) =>
-      react_1.default.createElement(
+  const renderEnumDescriptions = (0, utils_1.guard)(
+    getEnumDescriptionMarkdown(enumDescriptions),
+    (value) => {
+      return react_1.default.createElement(
         "div",
-        null,
+        { style: { marginTop: ".5rem" } },
         react_1.default.createElement(react_markdown_1.default, {
-          children: `**Default value:** \`${value}\``,
+          rehypePlugins: [rehype_raw_1.default],
+          remarkPlugins: [remark_gfm_1.default],
+          children: value,
         })
-      )
+      );
+    }
   );
+  function renderDefaultValue() {
+    if (defaultValue !== undefined) {
+      if (typeof defaultValue === "string") {
+        return react_1.default.createElement(
+          "div",
+          null,
+          react_1.default.createElement("strong", null, "Default value: "),
+          react_1.default.createElement(
+            "span",
+            null,
+            react_1.default.createElement("code", null, defaultValue)
+          )
+        );
+      }
+      return react_1.default.createElement(
+        "div",
+        null,
+        react_1.default.createElement("strong", null, "Default value: "),
+        react_1.default.createElement(
+          "span",
+          null,
+          react_1.default.createElement(
+            "code",
+            null,
+            JSON.stringify(defaultValue)
+          )
+        )
+      );
+    }
+    return undefined;
+  }
   const renderExample = (0, utils_1.guard)(
     (0, utils_1.toString)(example),
     (example) =>
@@ -186,8 +246,9 @@ function ParamsItem({
       renderDeprecated
     ),
     renderSchema,
-    renderDefaultValue,
     renderDescription,
+    renderEnumDescriptions,
+    renderDefaultValue(),
     renderExample,
     renderExamples
   );

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

@@ -0,0 +1,15 @@
+import React from "react";
+import { MediaTypeObject } from "docusaurus-plugin-openapi-docs/lib/openapi/types";
+interface Props {
+    style?: React.CSSProperties;
+    title: string;
+    body: {
+        content?: {
+            [key: string]: MediaTypeObject;
+        };
+        description?: string;
+        required?: string[] | boolean;
+    };
+}
+declare const RequestSchema: React.FC<Props>;
+export default RequestSchema;