docusaurus-theme-openapi-docs 4.2.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/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/ParamsItem/index.js

@@ -12,15 +12,11 @@ var __importDefault =
   };
 Object.defineProperty(exports, "__esModule", { value: true });
 const react_1 = __importDefault(require("react"));
-const CodeBlock_1 = __importDefault(require("@theme/CodeBlock"));
+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 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");
 const getEnumDescriptionMarkdown = (enumDescriptions) => {
@@ -80,46 +76,13 @@ function ParamsItem({ param, ...rest }) {
       "deprecated"
     )
   );
-  const renderSchema = (0, utils_1.guard)(
+  const renderQualifier = (0, utils_1.guard)(
     (0, schema_1.getQualifierMessage)(schema),
-    (message) =>
-      react_1.default.createElement(
-        "div",
-        null,
-        react_1.default.createElement(react_markdown_1.default, {
-          children: (0, createDescription_1.createDescription)(message),
-          rehypePlugins: [rehype_raw_1.default],
-        })
-      )
+    (qualifier) =>
+      react_1.default.createElement(Markdown_1.default, null, qualifier)
   );
   const renderDescription = (0, utils_1.guard)(description, (description) =>
-    react_1.default.createElement(
-      react_1.default.Fragment,
-      null,
-      react_1.default.createElement(react_markdown_1.default, {
-        children: (0, createDescription_1.createDescription)(description),
-        components: {
-          pre: "div",
-          code({ node, inline, className, children, ...props }) {
-            const match = /language-(\w+)/.exec(className || "");
-            if (inline)
-              return react_1.default.createElement("code", null, children);
-            return !inline && match
-              ? react_1.default.createElement(
-                  CodeBlock_1.default,
-                  { className: className },
-                  children
-                )
-              : react_1.default.createElement(
-                  CodeBlock_1.default,
-                  null,
-                  children
-                );
-          },
-        },
-        rehypePlugins: [rehype_raw_1.default],
-      })
-    )
+    react_1.default.createElement(Markdown_1.default, null, description)
   );
   const renderEnumDescriptions = (0, utils_1.guard)(
     getEnumDescriptionMarkdown(enumDescriptions),
@@ -127,11 +90,7 @@ function ParamsItem({ param, ...rest }) {
       return react_1.default.createElement(
         "div",
         { style: { marginTop: ".5rem" } },
-        react_1.default.createElement(react_markdown_1.default, {
-          rehypePlugins: [rehype_raw_1.default],
-          remarkPlugins: [remark_gfm_1.default],
-          children: value,
-        })
+        react_1.default.createElement(Markdown_1.default, null, value)
       );
     }
   );
@@ -245,7 +204,7 @@ function ParamsItem({ param, ...rest }) {
       renderSchemaRequired,
       renderDeprecated
     ),
-    renderSchema,
+    renderQualifier,
     renderDescription,
     renderEnumDescriptions,
     renderDefaultValue(),

package/lib/theme/RequestSchema/index.js

@@ -58,11 +58,11 @@ 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 Markdown_1 = __importDefault(require("@theme/Markdown"));
 const MimeTabs_1 = __importDefault(require("@theme/MimeTabs")); // Assume these components exist
 const Schema_1 = __importDefault(require("@theme/Schema"));
 const SkeletonLoader_1 = __importDefault(require("@theme/SkeletonLoader"));
 const TabItem_1 = __importDefault(require("@theme/TabItem"));
-const createDescription_1 = require("docusaurus-plugin-openapi-docs/lib/markdown/createDescription");
 const RequestSchemaComponent = ({ title, body, style }) => {
   if (
     body === undefined ||
@@ -128,7 +128,11 @@ const RequestSchemaComponent = ({ title, body, style }) => {
                   react_1.default.createElement(
                     "div",
                     { style: { marginTop: "1rem", marginBottom: "1rem" } },
-                    (0, createDescription_1.createDescription)(body.description)
+                    react_1.default.createElement(
+                      Markdown_1.default,
+                      null,
+                      body.description
+                    )
                   )
               ),
               react_1.default.createElement(
@@ -197,7 +201,11 @@ const RequestSchemaComponent = ({ title, body, style }) => {
             react_1.default.createElement(
               "div",
               { style: { marginTop: "1rem", marginBottom: "1rem" } },
-              (0, createDescription_1.createDescription)(body.description)
+              react_1.default.createElement(
+                Markdown_1.default,
+                null,
+                body.description
+              )
             )
         ),
         react_1.default.createElement(

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

@@ -1,48 +1,18 @@
 import React from "react";
 export declare function json2xml(o: Record<string, any>, tab: string): string;
-interface ParameterProps {
-    in: string;
-    name: string;
-    schema?: {
-        type?: string;
-        items?: Record<string, any>;
-    };
-    enumDescriptions?: [string, string][];
-}
-interface ResponseHeaderProps {
-    description?: string;
-    example?: string;
-    schema?: {
-        type?: string;
-    };
-}
-interface ResponseExampleProps {
-    value: any;
-    summary?: string;
-}
-interface Props {
-    parameters?: ParameterProps[];
-    type: string;
-    responseHeaders?: Record<string, ResponseHeaderProps>;
-    responseExamples?: Record<string, ResponseExampleProps>;
-    responseExample?: any;
-    schema?: any;
-    mimeType: string;
-}
-export declare const ParamsDetails: React.FC<Props>;
-export declare const ResponseHeaders: React.FC<{
-    responseHeaders?: Record<string, ResponseHeaderProps>;
-}>;
-export declare const ResponseExamples: React.FC<{
+interface ResponseExamplesProps {
     responseExamples: any;
     mimeType: string;
-}>;
-export declare const ResponseExample: React.FC<{
+}
+export declare const ResponseExamples: React.FC<ResponseExamplesProps>;
+interface ResponseExampleProps {
     responseExample: any;
     mimeType: string;
-}>;
-export declare const ExampleFromSchema: React.FC<{
+}
+export declare const ResponseExample: React.FC<ResponseExampleProps>;
+interface ExampleFromSchemaProps {
     schema: any;
     mimeType: string;
-}>;
+}
+export declare const ExampleFromSchema: React.FC<ExampleFromSchemaProps>;
 export {};

package/lib/theme/ResponseExamples/index.js

@@ -14,18 +14,14 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ExampleFromSchema =
   exports.ResponseExample =
   exports.ResponseExamples =
-  exports.ResponseHeaders =
-  exports.ParamsDetails =
   exports.json2xml =
     void 0;
 const react_1 = __importDefault(require("react"));
-const ParamsItem_1 = __importDefault(require("@theme/ParamsItem"));
+const Markdown_1 = __importDefault(require("@theme/Markdown"));
 const ResponseSamples_1 = __importDefault(require("@theme/ResponseSamples"));
 const TabItem_1 = __importDefault(require("@theme/TabItem"));
-const createDescription_1 = require("docusaurus-plugin-openapi-docs/lib/markdown/createDescription");
 const createResponseExample_1 = require("docusaurus-plugin-openapi-docs/lib/openapi/createResponseExample");
 const xml_formatter_1 = __importDefault(require("xml-formatter"));
-// Utility function
 function json2xml(o, tab) {
   const toXml = (v, name, ind) => {
     let xml = "";
@@ -63,98 +59,6 @@ function json2xml(o, tab) {
   return tab ? xml.replace(/\t/g, tab) : xml.replace(/\t|\n/g, "");
 }
 exports.json2xml = json2xml;
-// React components
-const ParamsDetails = ({ parameters, type }) => {
-  const params = parameters?.filter((param) => param?.in === type);
-  if (!params || params.length === 0) {
-    return null;
-  }
-  return react_1.default.createElement(
-    "details",
-    {
-      className: "openapi-markdown__details",
-      "data-collapsed": false,
-      open: true,
-      style: { marginBottom: "1rem" },
-    },
-    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`
-      )
-    ),
-    react_1.default.createElement(
-      "div",
-      null,
-      react_1.default.createElement(
-        "ul",
-        null,
-        params.map((param, index) =>
-          react_1.default.createElement(ParamsItem_1.default, {
-            key: index,
-            className: "paramsItem",
-            // @ts-ignore
-            param: {
-              ...param,
-              enumDescriptions: Object.entries(
-                param?.schema?.items?.["x-enumDescriptions"] ?? {}
-              ),
-            },
-          })
-        )
-      )
-    )
-  );
-};
-exports.ParamsDetails = ParamsDetails;
-const ResponseHeaders = ({ responseHeaders }) => {
-  if (!responseHeaders) {
-    return null;
-  }
-  return react_1.default.createElement(
-    "ul",
-    { style: { marginLeft: "1rem" } },
-    Object.entries(responseHeaders).map(([headerName, headerObj]) => {
-      const { description, example, schema } = headerObj;
-      const type = schema?.type ?? "any";
-      return react_1.default.createElement(
-        "li",
-        { className: "schemaItem", key: headerName },
-        react_1.default.createElement(
-          "details",
-          null,
-          react_1.default.createElement(
-            "summary",
-            null,
-            react_1.default.createElement("strong", null, headerName),
-            type &&
-              react_1.default.createElement(
-                "span",
-                { style: { opacity: "0.6" } },
-                " ",
-                type
-              )
-          ),
-          react_1.default.createElement(
-            "div",
-            null,
-            description &&
-              react_1.default.createElement(
-                "div",
-                { style: { marginTop: ".5rem", marginBottom: ".5rem" } },
-                example && `Example: ${example}`,
-                (0, createDescription_1.createDescription)(description)
-              )
-          )
-        )
-      );
-    })
-  );
-};
-exports.ResponseHeaders = ResponseHeaders;
 const ResponseExamples = ({ responseExamples, mimeType }) => {
   let language = "shell";
   if (mimeType.endsWith("json")) language = "json";
@@ -173,7 +77,7 @@ const ResponseExamples = ({ responseExamples, mimeType }) => {
           { label: exampleName, value: exampleName, key: exampleName },
           exampleValue.summary &&
             react_1.default.createElement(
-              "div",
+              Markdown_1.default,
               { className: "openapi-example__summary" },
               exampleValue.summary
             ),
@@ -207,7 +111,7 @@ const ResponseExample = ({ responseExample, mimeType }) => {
       { label: "Example", value: "Example" },
       responseExample.summary &&
         react_1.default.createElement(
-          "div",
+          Markdown_1.default,
           { className: "openapi-example__summary" },
           responseExample.summary
         ),

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

@@ -0,0 +1,13 @@
+import React from "react";
+interface ResponseHeadersProps {
+    description?: string;
+    example?: string;
+    schema?: {
+        type?: string;
+        format?: string;
+    };
+}
+export declare const ResponseHeaders: React.FC<{
+    responseHeaders?: Record<string, ResponseHeadersProps>;
+}>;
+export default ResponseHeaders;

package/lib/theme/ResponseHeaders/index.js

@@ -0,0 +1,39 @@
+"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.ResponseHeaders = void 0;
+const react_1 = __importDefault(require("react"));
+const SchemaItem_1 = __importDefault(require("@theme/SchemaItem"));
+const schema_1 = require("../../markdown/schema");
+const ResponseHeaders = ({ responseHeaders }) => {
+  if (!responseHeaders) {
+    return null;
+  }
+  return react_1.default.createElement(
+    "ul",
+    { style: { marginLeft: "1rem" } },
+    Object.entries(responseHeaders).map(([name, schema]) => {
+      return react_1.default.createElement(SchemaItem_1.default, {
+        name: name,
+        collapsible: false,
+        schemaName: (0, schema_1.getSchemaName)(schema),
+        qualifierMessage: (0, schema_1.getQualifierMessage)(schema),
+        schema: schema,
+        discriminator: false,
+        children: null,
+      });
+    })
+  );
+};
+exports.ResponseHeaders = ResponseHeaders;
+exports.default = exports.ResponseHeaders;