docusaurus-theme-openapi-docs 4.1.0 → 4.3.0

package/src/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/src/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/src/theme/ParamsDetails/index.tsx

@@ -0,0 +1,88 @@
+/* ============================================================================
+ * 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.
+ * ========================================================================== */
+
+import React, { Suspense } from "react";
+
+import BrowserOnly from "@docusaurus/BrowserOnly";
+import Details from "@theme/Details";
+import ParamsItem from "@theme/ParamsItem";
+import SkeletonLoader from "@theme/SkeletonLoader";
+
+interface Props {
+  parameters: any[];
+}
+
+const ParamsDetailsComponent: React.FC<Props> = ({ parameters }) => {
+  const types = ["path", "query", "header", "cookie"];
+
+  return (
+    <>
+      {types.map((type) => {
+        const params = parameters?.filter((param: any) => param?.in === type);
+
+        if (!params || params.length === 0) {
+          return null;
+        }
+
+        const summaryElement = (
+          <summary>
+            <h3 className="openapi-markdown__details-summary-header-params">
+              {`${type.charAt(0).toUpperCase() + type.slice(1)} Parameters`}
+            </h3>
+          </summary>
+        );
+
+        return (
+          <Details
+            key={type}
+            className="openapi-markdown__details"
+            style={{ marginBottom: "1rem" }}
+            data-collapsed={false}
+            open={true}
+            summary={summaryElement}
+          >
+            <ul>
+              {params.map((param: any, index: number) => (
+                <ParamsItem
+                  key={index}
+                  className="paramsItem"
+                  param={{
+                    ...param,
+                    enumDescriptions: Object.entries(
+                      param?.schema?.["x-enumDescriptions"] ??
+                        param?.schema?.items?.["x-enumDescriptions"] ??
+                        {}
+                    ),
+                  }}
+                />
+              ))}
+            </ul>
+          </Details>
+        );
+      })}
+    </>
+  );
+};
+
+const ParamsDetails: React.FC<Props> = (props) => {
+  return (
+    <BrowserOnly fallback={<SkeletonLoader size="sm" />}>
+      {() => {
+        const LazyComponent = React.lazy(() =>
+          Promise.resolve({ default: ParamsDetailsComponent })
+        );
+        return (
+          <Suspense fallback={null}>
+            <LazyComponent {...props} />
+          </Suspense>
+        );
+      }}
+    </BrowserOnly>
+  );
+};
+
+export default ParamsDetails;

package/src/theme/ParamsItem/index.tsx

@@ -7,16 +7,12 @@
 
 import React from "react";
 
-import CodeBlock from "@theme/CodeBlock";
+import Markdown from "@theme/Markdown";
 import SchemaTabs from "@theme/SchemaTabs";
 import TabItem from "@theme/TabItem";
 /* eslint-disable import/no-extraneous-dependencies*/
 import clsx from "clsx";
-import ReactMarkdown from "react-markdown";
-import rehypeRaw from "rehype-raw";
-import remarkGfm from "remark-gfm";
 
-import { createDescription } from "../../markdown/createDescription";
 import { getQualifierMessage, getSchemaName } from "../../markdown/schema";
 import { guard, toString } from "../../markdown/utils";
 
@@ -32,6 +28,7 @@ export interface ExampleObject {
 }
 
 export interface Props {
+  className: string;
   param: {
     description: string;
     example: any;
@@ -96,45 +93,21 @@ function ParamsItem({ param, ...rest }: Props) {
     <span className="openapi-schema__deprecated">deprecated</span>
   ));
 
-  const renderSchema = guard(getQualifierMessage(schema), (message) => (
-    <div>
-      <ReactMarkdown
-        children={createDescription(message)}
-        rehypePlugins={[rehypeRaw]}
-      />
-    </div>
+  const renderQualifier = guard(getQualifierMessage(schema), (qualifier) => (
+    <Markdown>{qualifier}</Markdown>
   ));
 
   const renderDescription = guard(description, (description) => (
-    <div>
-      <ReactMarkdown
-        children={createDescription(description)}
-        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>
-            );
-          },
-        }}
-        rehypePlugins={[rehypeRaw]}
-      />
-    </div>
+    <Markdown>{description}</Markdown>
   ));
 
   const renderEnumDescriptions = guard(
     getEnumDescriptionMarkdown(enumDescriptions),
     (value) => {
       return (
-        <ReactMarkdown
-          rehypePlugins={[rehypeRaw]}
-          remarkPlugins={[remarkGfm]}
-          children={value}
-        />
+        <div style={{ marginTop: ".5rem" }}>
+          <Markdown>{value}</Markdown>
+        </div>
       );
     }
   );
@@ -214,7 +187,7 @@ function ParamsItem({ param, ...rest }: Props) {
         {renderSchemaRequired}
         {renderDeprecated}
       </span>
-      {renderSchema}
+      {renderQualifier}
       {renderDescription}
       {renderEnumDescriptions}
       {renderDefaultValue()}

package/src/theme/RequestSchema/index.tsx

@@ -0,0 +1,164 @@
+/* ============================================================================
+ * 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.
+ * ========================================================================== */
+
+import React, { Suspense } from "react";
+
+import BrowserOnly from "@docusaurus/BrowserOnly";
+import Details from "@theme/Details";
+import Markdown from "@theme/Markdown";
+import MimeTabs from "@theme/MimeTabs"; // Assume these components exist
+import SchemaNode from "@theme/Schema";
+import SkeletonLoader from "@theme/SkeletonLoader";
+import TabItem from "@theme/TabItem";
+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;
+  };
+}
+
+const RequestSchemaComponent: React.FC<Props> = ({ title, body, style }) => {
+  if (
+    body === undefined ||
+    body.content === undefined ||
+    Object.keys(body).length === 0 ||
+    Object.keys(body.content).length === 0
+  ) {
+    return null;
+  }
+
+  const mimeTypes = Object.keys(body.content);
+
+  if (mimeTypes.length > 1) {
+    return (
+      <MimeTabs className="openapi-tabs__mime" schemaType="request">
+        {mimeTypes.map((mimeType) => {
+          const firstBody = body.content![mimeType].schema;
+          if (
+            firstBody === undefined ||
+            (firstBody.properties &&
+              Object.keys(firstBody.properties).length === 0)
+          ) {
+            return null;
+          }
+          return (
+            // @ts-ignore
+            <TabItem key={mimeType} label={mimeType} value={mimeType}>
+              <Details
+                className="openapi-markdown__details mime"
+                data-collapsed={false}
+                open={true}
+                style={style}
+                summary={
+                  <>
+                    <summary>
+                      <h3 className="openapi-markdown__details-summary-header-body">
+                        {title}
+                        {body.required === true && (
+                          <span className="openapi-schema__required">
+                            required
+                          </span>
+                        )}
+                      </h3>
+                    </summary>
+                  </>
+                }
+              >
+                <div style={{ textAlign: "left", marginLeft: "1rem" }}>
+                  {body.description && (
+                    <div style={{ marginTop: "1rem", marginBottom: "1rem" }}>
+                      <Markdown>{body.description}</Markdown>
+                    </div>
+                  )}
+                </div>
+                <ul style={{ marginLeft: "1rem" }}>
+                  <SchemaNode schema={firstBody} schemaType="request" />
+                </ul>
+              </Details>
+            </TabItem>
+          );
+        })}
+      </MimeTabs>
+    );
+  }
+
+  const randomFirstKey = mimeTypes[0];
+  const firstBody =
+    body.content[randomFirstKey].schema ?? body.content![randomFirstKey];
+
+  if (firstBody === undefined) {
+    return null;
+  }
+
+  return (
+    <MimeTabs className="openapi-tabs__mime" schemaType="request">
+      {/* @ts-ignore */}
+      <TabItem label={randomFirstKey} value={`${randomFirstKey}-schema`}>
+        <Details
+          className="openapi-markdown__details mime"
+          data-collapsed={false}
+          open={true}
+          style={style}
+          summary={
+            <>
+              <summary>
+                <h3 className="openapi-markdown__details-summary-header-body">
+                  {title}
+                  {firstBody.type === "array" && (
+                    <span style={{ opacity: "0.6" }}> array</span>
+                  )}
+                  {body.required && (
+                    <strong className="openapi-schema__required">
+                      required
+                    </strong>
+                  )}
+                </h3>
+              </summary>
+            </>
+          }
+        >
+          <div style={{ textAlign: "left", marginLeft: "1rem" }}>
+            {body.description && (
+              <div style={{ marginTop: "1rem", marginBottom: "1rem" }}>
+                <Markdown>{body.description}</Markdown>
+              </div>
+            )}
+          </div>
+          <ul style={{ marginLeft: "1rem" }}>
+            <SchemaNode schema={firstBody} schemaType="request" />
+          </ul>
+        </Details>
+      </TabItem>
+    </MimeTabs>
+  );
+};
+
+const RequestSchema: React.FC<Props> = (props) => {
+  return (
+    <BrowserOnly fallback={<SkeletonLoader size="sm" />}>
+      {() => {
+        const LazyComponent = React.lazy(() =>
+          Promise.resolve({ default: RequestSchemaComponent })
+        );
+        return (
+          <Suspense fallback={null}>
+            <LazyComponent {...props} />
+          </Suspense>
+        );
+      }}
+    </BrowserOnly>
+  );
+};
+
+export default RequestSchema;