docusaurus-theme-openapi-docs 4.1.0 → 4.3.0

package/lib/theme/ApiExplorer/ApiCodeBlock/Line/_Line.scss

@@ -8,13 +8,6 @@ the background in custom CSS file due bug https://github.com/facebook/docusaurus
   --docusaurus-highlighted-code-line-bg: rgb(100 100 100);
 }
 
-.theme-code-block-highlighted-line {
-  background-color: var(--docusaurus-highlighted-code-line-bg);
-  display: block;
-  margin: 0 calc(-1 * var(--ifm-pre-padding));
-  padding: 0 var(--ifm-pre-padding);
-}
-
 .openapi-explorer__code-block-code-line {
   display: table-row;
   counter-increment: line-count;
@@ -36,11 +29,6 @@ the background in custom CSS file due bug https://github.com/facebook/docusaurus
   opacity: 0.4;
 }
 
-:global(.theme-code-block-highlighted-line)
-  .openapi-explorer__code-block-code-line-number::before {
-  opacity: 0.8;
-}
-
 .openapi-explorer__code-block-code-line-number {
   padding-right: var(--ifm-pre-padding);
 }

package/lib/theme/ApiExplorer/Authorization/index.js

@@ -53,6 +53,7 @@ function Authorization() {
           { label: "Bearer Token", key: a.key + "-bearer" },
           react_1.default.createElement(FormTextInput_1.default, {
             placeholder: "Bearer Token",
+            password: true,
             value: data[a.key].token ?? "",
             onChange: (e) => {
               const value = e.target.value;
@@ -73,6 +74,7 @@ function Authorization() {
           { label: "Bearer Token", key: a.key + "-oauth2" },
           react_1.default.createElement(FormTextInput_1.default, {
             placeholder: "Bearer Token",
+            password: true,
             value: data[a.key].token ?? "",
             onChange: (e) => {
               const value = e.target.value;
@@ -136,6 +138,7 @@ function Authorization() {
           { label: `${a.key}`, key: a.key + "-apikey" },
           react_1.default.createElement(FormTextInput_1.default, {
             placeholder: `${a.key}`,
+            password: true,
             value: data[a.key].apiKey ?? "",
             onChange: (e) => {
               const value = e.target.value;

package/lib/theme/ApiExplorer/Body/index.js

@@ -23,6 +23,7 @@ const FormTextInput_1 = __importDefault(
 );
 const LiveEditor_1 = __importDefault(require("@theme/ApiExplorer/LiveEditor"));
 const hooks_1 = require("@theme/ApiItem/hooks");
+const Markdown_1 = __importDefault(require("@theme/Markdown"));
 const SchemaTabs_1 = __importDefault(require("@theme/SchemaTabs"));
 const TabItem_1 = __importDefault(require("@theme/TabItem"));
 const xml_formatter_1 = __importDefault(require("xml-formatter"));
@@ -297,7 +298,11 @@ function Body({
           TabItem_1.default,
           { label: "Example", value: "example" },
           example.summary &&
-            react_1.default.createElement("div", null, example.summary),
+            react_1.default.createElement(
+              Markdown_1.default,
+              null,
+              example.summary
+            ),
           exampleBody &&
             react_1.default.createElement(
               LiveEditor_1.default,
@@ -339,7 +344,11 @@ function Body({
                 key: example.label,
               },
               example.summary &&
-                react_1.default.createElement("div", null, example.summary),
+                react_1.default.createElement(
+                  Markdown_1.default,
+                  null,
+                  example.summary
+                ),
               example.body &&
                 react_1.default.createElement(
                   LiveEditor_1.default,

package/lib/theme/ApiExplorer/CodeSnippets/index.js

@@ -224,7 +224,7 @@ function CodeSnippets({ postman, codeSamples }) {
   ]);
   // no dependencies was intentionlly set for this particular hook. it's safe as long as if conditions are set
   (0, react_1.useEffect)(function onSelectedVariantUpdate() {
-    if (selectedVariant && selectedVariant !== language.variant) {
+    if (selectedVariant && selectedVariant !== language?.variant) {
       const postmanRequest = (0, buildPostmanRequest_1.default)(postman, {
         queryParams,
         pathParams,
@@ -254,6 +254,7 @@ function CodeSnippets({ postman, codeSamples }) {
   // eslint-disable-next-line react-hooks/exhaustive-deps
   (0, react_1.useEffect)(function onSelectedSampleUpdate() {
     if (
+      language &&
       language.samples &&
       language.samplesSources &&
       selectedSample &&

package/lib/theme/ApiExplorer/CodeTabs/_CodeTabs.scss

@@ -436,6 +436,56 @@ body[class="ReactModal__Body--open"] {
   }
 }
 
+.openapi-tabs__code-item--http {
+  color: var(--ifm-color-gray-500);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  position: relative;
+
+  &::after {
+    content: "";
+    display: inline-block;
+    width: 32px; /* Explicitly setting width to 32 pixels */
+    height: 32px; /* Explicitly setting height to 32 pixels */
+    background-image: url("data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMzIiIGhlaWdodD0iMzIiIHZpZXdCb3g9IjAgMCAzMiAzMiIgZmlsbD0ibm9uZSIgc3Ryb2tlPSJjdXJyZW50Q29sb3IiIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyI+PHBhdGggZD0iTTEyIDIyTDggMTZMMTIgMTBNMjAgMjJMMjQgMTZMIDIwIDEwIiBzdHJva2U9ImN1cnJlbnRDb2xvciIgc3Ryb2tlLXdpZHRoPSIyIiBzdHJva2UtbGluZWNhcD0icm91bmQiIHN0cm9rZS1saW5lam9pbj0icm91bmQiLz48L3N2Zz4=");
+    background-size: contain;
+    background-repeat: no-repeat;
+    background-position: center; /* Center the SVG */
+    margin-top: 0.5rem;
+  }
+
+  &.active {
+    box-shadow: 0 0 0 3px var(--opeanpi-code-tab-shadow-color-http);
+    border-color: var(--openapi-code-tab-border-color-http);
+  }
+}
+
+.openapi-tabs__code-item--shell {
+  color: var(--ifm-color-gray-500);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  position: relative;
+
+  &::after {
+    content: "";
+    display: inline-block;
+    width: 32px; /* Explicitly setting width to 32 pixels */
+    height: 32px; /* Explicitly setting height to 32 pixels */
+    background-image: url("data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMzIiIGhlaWdodD0iMzIiIHZpZXdCb3g9IjAgMCAzMiAzMiIgZmlsbD0ibm9uZSIgc3Ryb2tlPSJjdXJyZW50Q29sb3IiIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyI+PHBhdGggZD0iTTEyIDIyTDggMTZMMTIgMTBNMjAgMjJMMjQgMTZMIDIwIDEwIiBzdHJva2U9ImN1cnJlbnRDb2xvciIgc3Ryb2tlLXdpZHRoPSIyIiBzdHJva2UtbGluZWNhcD0icm91bmQiIHN0cm9rZS1saW5lam9pbj0icm91bmQiLz48L3N2Zz4=");
+    background-size: contain;
+    background-repeat: no-repeat;
+    background-position: center; /* Center the SVG */
+    margin-top: 0.5rem;
+  }
+
+  &.active {
+    box-shadow: 0 0 0 3px var(--opeanpi-code-tab-shadow-color-shell);
+    border-color: var(--openapi-code-tab-border-color-shell);
+  }
+}
+
 @media only screen and (min-width: 768px) and (max-width: 996px) {
   .openapi-tabs__code-list {
     justify-content: space-around;

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

@@ -53,6 +53,7 @@ function DocItemLayout({ children }) {
   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" },
@@ -86,7 +87,7 @@ function DocItemLayout({ children }) {
               {
                 className: (0, clsx_1.default)(
                   "col",
-                  api ? "col--7" : "col--12"
+                  api || schema ? "col--7" : "col--12"
                 ),
               },
               react_1.default.createElement(Footer_1.default, null)
@@ -99,7 +100,10 @@ function DocItemLayout({ children }) {
           react_1.default.createElement(
             "div",
             {
-              className: (0, clsx_1.default)("col", api ? "col--7" : "col--12"),
+              className: (0, clsx_1.default)(
+                "col",
+                api || schema ? "col--7" : "col--12"
+              ),
             },
             react_1.default.createElement(Paginator_1.default, null)
           )

package/lib/theme/ApiItem/index.js

@@ -26,7 +26,9 @@ 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/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/Markdown/Details/_Details.scss

@@ -23,10 +23,13 @@
 
 /* Top-Level Details Caret Styling */
 .openapi-left-panel__container > .openapi-markdown__details > summary::before,
-.openapi-markdown__details.mime > summary::before,
-.openapi-markdown__details.response > summary::before {
+.openapi-markdown__details.mime > summary::before {
   top: 0.1rem;
 }
+
+.openapi-markdown__details.response > summary::before {
+  top: 0.25rem; /* TODO: figure out why this is necessary */
+}
 /* End of Top-Level Details Caret Styling */
 
 .openapi-markdown__details {

package/lib/theme/Markdown/index.js

@@ -7,30 +7,172 @@
 
 import React from "react";
 
+import Admonition from "@theme/Admonition";
 import CodeBlock from "@theme/CodeBlock";
 import ReactMarkdown from "react-markdown";
 import rehypeRaw from "rehype-raw";
+import remarkGfm from "remark-gfm";
+
+function remarkAdmonition() {
+  return (tree) => {
+    const openingTagRegex = /^:::(\w+)(?:\[(.*?)\])?\s*$/;
+    const closingTagRegex = /^:::\s*$/;
+    const textOnlyAdmonition = /^:::(\w+)(?:\[(.*?)\])?\s*([\s\S]*?)\s*:::$/;
+
+    const nodes = [];
+    let bufferedChildren = [];
+
+    let insideAdmonition = false;
+    let type = null;
+    let title = null;
+
+    tree.children.forEach((node) => {
+      if (
+        node.type === "paragraph" &&
+        node.children.length === 1 &&
+        node.children[0].type === "text"
+      ) {
+        const text = node.children[0].value.trim();
+        const openingMatch = text.match(openingTagRegex);
+        const closingMatch = text.match(closingTagRegex);
+        const textOnlyAdmonitionMatch = text.match(textOnlyAdmonition);
+
+        if (textOnlyAdmonitionMatch) {
+          const type = textOnlyAdmonitionMatch[1];
+          const title = textOnlyAdmonitionMatch[2]
+            ? textOnlyAdmonitionMatch[2]?.trim()
+            : undefined;
+          const content = textOnlyAdmonitionMatch[3];
+
+          const admonitionNode = {
+            type: "admonition",
+            data: {
+              hName: "Admonition", // Tells ReactMarkdown to replace the node with Admonition component
+              hProperties: {
+                type, // Passed as a prop to the Admonition component
+                title,
+              },
+            },
+            children: [
+              {
+                type: "text",
+                value: content?.trim(), // Trim leading/trailing whitespace
+              },
+            ],
+          };
+          nodes.push(admonitionNode);
+          return;
+        }
+
+        if (openingMatch) {
+          type = openingMatch[1];
+          title = openingMatch[2] || type;
+          insideAdmonition = true;
+          return;
+        }
+
+        if (closingMatch && insideAdmonition) {
+          nodes.push({
+            type: "admonition",
+            data: {
+              hName: "Admonition",
+              hProperties: { type: type, title: title },
+            },
+            children: bufferedChildren,
+          });
+          bufferedChildren = [];
+          insideAdmonition = false;
+          type = null;
+          title = null;
+          return;
+        }
+      }
+
+      if (insideAdmonition) {
+        bufferedChildren.push(node);
+      } else {
+        nodes.push(node);
+      }
+    });
+
+    if (bufferedChildren.length > 0 && type) {
+      nodes.push({
+        type: "admonition",
+        data: {
+          hName: "Admonition",
+          hProperties: { type: type, title: title },
+        },
+        children: bufferedChildren,
+      });
+    }
+    tree.children = nodes;
+  };
+}
+
+function convertAstToHtmlStr(ast) {
+  if (!ast || !Array.isArray(ast)) {
+    return "";
+  }
+
+  const convertNode = (node) => {
+    switch (node.type) {
+      case "text":
+        return node.value;
+      case "element":
+        const { tagName, properties, children } = node;
+
+        // Convert attributes to a string
+        const attrs = properties
+          ? Object.entries(properties)
+              .map(([key, value]) => `${key}="${value}"`)
+              .join(" ")
+          : "";
+
+        // Convert children to HTML
+        const childrenHtml = children ? children.map(convertNode).join("") : "";
+
+        return `<${tagName} ${attrs}>${childrenHtml}</${tagName}>`;
+      default:
+        return "";
+    }
+  };
+
+  return ast.map(convertNode).join("");
+}
 
 function Markdown({ children }) {
   return (
-    <div>
-      <ReactMarkdown
-        children={children}
-        rehypePlugins={[rehypeRaw]}
-        components={{
-          pre: "div",
-          code({ node, inline, className, children, ...props }) {
-            const match = /language-(\w+)/.exec(className || "");
-            if (inline) return <code>{children}</code>;
-            return !inline && match ? (
-              <CodeBlock className={className}>{children}</CodeBlock>
-            ) : (
-              <CodeBlock>{children}</CodeBlock>
-            );
-          },
-        }}
-      />
-    </div>
+    <ReactMarkdown
+      rehypePlugins={[rehypeRaw]}
+      remarkPlugins={[remarkGfm, remarkAdmonition]}
+      components={{
+        pre: (props) => <div {...props} />,
+        code({ node, inline, className, children, ...props }) {
+          const match = /language-(\w+)/.exec(className || "");
+          return match ? (
+            <CodeBlock className={className} language={match[1]} {...props}>
+              {children}
+            </CodeBlock>
+          ) : (
+            <code className={className} {...props}>
+              {children}
+            </code>
+          );
+        },
+        admonition: ({ node, ...props }) => {
+          const type = node.data?.hProperties?.type || "note";
+          const title = node.data?.hProperties?.title || type;
+          const content = convertAstToHtmlStr(node.children);
+          return (
+            <Admonition type={type} title={title} {...props}>
+              <div dangerouslySetInnerHTML={{ __html: content }} />
+            </Admonition>
+          );
+        },
+      }}
+    >
+      {children}
+    </ReactMarkdown>
   );
 }
 

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;