docusaurus-theme-openapi-docs 4.2.0 → 4.3.1

package/src/theme/ApiExplorer/CodeSnippets/index.tsx

@@ -5,13 +5,6 @@
  * LICENSE file in the root directory of this source tree.
  * ========================================================================== */
 
-/* ============================================================================
- * 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, { useState, useEffect } from "react";
 
 import useDocusaurusContext from "@docusaurus/useDocusaurusContext";
@@ -19,6 +12,7 @@ import ApiCodeBlock from "@theme/ApiExplorer/ApiCodeBlock";
 import buildPostmanRequest from "@theme/ApiExplorer/buildPostmanRequest";
 import CodeTabs from "@theme/ApiExplorer/CodeTabs";
 import { useTypedSelector } from "@theme/ApiItem/hooks";
+import cloneDeep from "lodash/cloneDeep";
 import codegen from "postman-code-generators";
 import sdk from "postman-collection";
 
@@ -59,6 +53,44 @@ function CodeSnippets({ postman, codeSamples }: Props) {
   const headerParams = useTypedSelector((state: any) => state.params.header);
 
   const auth = useTypedSelector((state: any) => state.auth);
+  const clonedAuth = cloneDeep(auth);
+  let placeholder: string;
+
+  function cleanCredentials(obj: any) {
+    for (const key in obj) {
+      if (typeof obj[key] === "object" && obj[key] !== null) {
+        // use name as placeholder if exists
+        const comboAuthId = Object.keys(obj).join(" and ");
+        const authOptions =
+          clonedAuth?.options?.[key] ?? clonedAuth?.options?.[comboAuthId];
+        placeholder = authOptions?.[0]?.name;
+        obj[key] = cleanCredentials(obj[key]);
+      } else {
+        obj[key] = `<${placeholder ?? key}>`;
+      }
+    }
+
+    return obj;
+  }
+
+  // scrub credentials from code snippets
+  const cleanedAuth = {
+    ...clonedAuth,
+    data: cleanCredentials(clonedAuth.data),
+  };
+
+  // Create a Postman request object using cleanedAuth
+  const cleanedPostmanRequest = buildPostmanRequest(postman, {
+    queryParams,
+    pathParams,
+    cookieParams,
+    contentType,
+    accept,
+    headerParams,
+    body,
+    server,
+    auth: cleanedAuth,
+  });
 
   // User-defined languages array
   // Can override languageSet, change order of langs, override options and variants
@@ -105,21 +137,10 @@ function CodeSnippets({ postman, codeSamples }: Props) {
     }
 
     if (language && !!language.options) {
-      const postmanRequest = buildPostmanRequest(postman, {
-        queryParams,
-        pathParams,
-        cookieParams,
-        contentType,
-        accept,
-        headerParams,
-        body,
-        server,
-        auth,
-      });
       codegen.convert(
         language.language,
         language.variant,
-        postmanRequest,
+        cleanedPostmanRequest,
         language.options,
         (error: any, snippet: string) => {
           if (error) {
@@ -137,22 +158,10 @@ function CodeSnippets({ postman, codeSamples }: Props) {
       // This allows users to define only the minimal properties necessary in languageTabs
       // User-defined properties should override languageSet properties
       const mergedLanguage = { ...langSource[0], ...language };
-      const postmanRequest = buildPostmanRequest(postman, {
-        queryParams,
-        pathParams,
-        cookieParams,
-        contentType,
-        accept,
-        headerParams,
-        body,
-        server,
-        auth,
-      });
-
       codegen.convert(
         mergedLanguage.language,
         mergedLanguage.variant,
-        postmanRequest,
+        cleanedPostmanRequest,
         mergedLanguage.options,
         (error: any, snippet: string) => {
           if (error) {
@@ -175,27 +184,16 @@ function CodeSnippets({ postman, codeSamples }: Props) {
     postman,
     queryParams,
     server,
-    auth,
+    cleanedPostmanRequest,
     mergedLangs,
   ]);
-  // no dependencies was intentionlly set for this particular hook. it's safe as long as if conditions are set
+  // no dependencies was intentionally set for this particular hook. it's safe as long as if conditions are set
   useEffect(function onSelectedVariantUpdate() {
     if (selectedVariant && selectedVariant !== language?.variant) {
-      const postmanRequest = buildPostmanRequest(postman, {
-        queryParams,
-        pathParams,
-        cookieParams,
-        contentType,
-        accept,
-        headerParams,
-        body,
-        server,
-        auth,
-      });
       codegen.convert(
         language.language,
         selectedVariant,
-        postmanRequest,
+        cleanedPostmanRequest,
         language.options,
         (error: any, snippet: string) => {
           if (error) {
@@ -207,7 +205,7 @@ function CodeSnippets({ postman, codeSamples }: Props) {
     }
   });
 
-  // no dependencies was intentionlly set for this particular hook. it's safe as long as if conditions are set
+  // no dependencies was intentionally set for this particular hook. it's safe as long as if conditions are set
   // eslint-disable-next-line react-hooks/exhaustive-deps
   useEffect(function onSelectedSampleUpdate() {
     if (

package/src/theme/ApiExplorer/buildPostmanRequest.ts

@@ -298,7 +298,7 @@ function buildPostmanRequest(
       if (apiKey === undefined) {
         otherHeaders.push({
           key: a.name,
-          value: "<API_KEY_VALUE>",
+          value: `<${a.name ?? a.type}>`,
         });
         continue;
       }

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/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";
 
@@ -97,34 +93,12 @@ 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) => (
-    <>
-      <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]}
-      />
-    </>
+    <Markdown>{description}</Markdown>
   ));
 
   const renderEnumDescriptions = guard(
@@ -132,11 +106,7 @@ function ParamsItem({ param, ...rest }: Props) {
     (value) => {
       return (
         <div style={{ marginTop: ".5rem" }}>
-          <ReactMarkdown
-            rehypePlugins={[rehypeRaw]}
-            remarkPlugins={[remarkGfm]}
-            children={value}
-          />
+          <Markdown>{value}</Markdown>
         </div>
       );
     }
@@ -217,7 +187,7 @@ function ParamsItem({ param, ...rest }: Props) {
         {renderSchemaRequired}
         {renderDeprecated}
       </span>
-      {renderSchema}
+      {renderQualifier}
       {renderDescription}
       {renderEnumDescriptions}
       {renderDefaultValue()}

package/src/theme/RequestSchema/index.tsx

@@ -9,11 +9,11 @@ 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 { createDescription } from "docusaurus-plugin-openapi-docs/lib/markdown/createDescription";
 import { MediaTypeObject } from "docusaurus-plugin-openapi-docs/lib/openapi/types";
 
 interface Props {
@@ -78,7 +78,7 @@ const RequestSchemaComponent: React.FC<Props> = ({ title, body, style }) => {
                 <div style={{ textAlign: "left", marginLeft: "1rem" }}>
                   {body.description && (
                     <div style={{ marginTop: "1rem", marginBottom: "1rem" }}>
-                      {createDescription(body.description)}
+                      <Markdown>{body.description}</Markdown>
                     </div>
                   )}
                 </div>
@@ -131,7 +131,7 @@ const RequestSchemaComponent: React.FC<Props> = ({ title, body, style }) => {
           <div style={{ textAlign: "left", marginLeft: "1rem" }}>
             {body.description && (
               <div style={{ marginTop: "1rem", marginBottom: "1rem" }}>
-                {createDescription(body.description)}
+                <Markdown>{body.description}</Markdown>
               </div>
             )}
           </div>

package/src/theme/ResponseExamples/index.tsx

@@ -7,14 +7,12 @@
 
 import React from "react";
 
-import ParamsItem from "@theme/ParamsItem";
+import Markdown from "@theme/Markdown";
 import ResponseSamples from "@theme/ResponseSamples";
 import TabItem from "@theme/TabItem";
-import { createDescription } from "docusaurus-plugin-openapi-docs/lib/markdown/createDescription";
 import { sampleResponseFromSchema } from "docusaurus-plugin-openapi-docs/lib/openapi/createResponseExample";
 import format from "xml-formatter";
 
-// Utility function
 export function json2xml(o: Record<string, any>, tab: string): string {
   const toXml = (v: any, name: string, ind: string): string => {
     let xml = "";
@@ -52,120 +50,14 @@ export function json2xml(o: Record<string, any>, tab: string): string {
   return tab ? xml.replace(/\t/g, tab) : xml.replace(/\t|\n/g, "");
 }
 
-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;
-}
-
-// React components
-export const ParamsDetails: React.FC<Props> = ({ parameters, type }) => {
-  const params = parameters?.filter((param) => param?.in === type);
-
-  if (!params || params.length === 0) {
-    return null;
-  }
-
-  return (
-    <details
-      className="openapi-markdown__details"
-      data-collapsed={false}
-      open={true}
-      style={{ marginBottom: "1rem" }}
-    >
-      <summary>
-        <h3 className="openapi-markdown__details-summary-header-params">
-          {`${type.charAt(0).toUpperCase() + type.slice(1)} Parameters`}
-        </h3>
-      </summary>
-      <div>
-        <ul>
-          {params.map((param, index) => (
-            <ParamsItem
-              key={index}
-              className="paramsItem"
-              // @ts-ignore
-              param={{
-                ...param,
-                enumDescriptions: Object.entries(
-                  param?.schema?.items?.["x-enumDescriptions"] ?? {}
-                ),
-              }}
-            />
-          ))}
-        </ul>
-      </div>
-    </details>
-  );
-};
-
-export const ResponseHeaders: React.FC<{
-  responseHeaders?: Record<string, ResponseHeaderProps>;
-}> = ({ responseHeaders }) => {
-  if (!responseHeaders) {
-    return null;
-  }
-
-  return (
-    <ul style={{ marginLeft: "1rem" }}>
-      {Object.entries(responseHeaders).map(([headerName, headerObj]) => {
-        const { description, example, schema } = headerObj;
-        const type = schema?.type ?? "any";
-
-        return (
-          <li className="schemaItem" key={headerName}>
-            <details>
-              <summary>
-                <strong>{headerName}</strong>
-                {type && <span style={{ opacity: "0.6" }}> {type}</span>}
-              </summary>
-              <div>
-                {description && (
-                  <div style={{ marginTop: ".5rem", marginBottom: ".5rem" }}>
-                    {example && `Example: ${example}`}
-                    {createDescription(description)}
-                  </div>
-                )}
-              </div>
-            </details>
-          </li>
-        );
-      })}
-    </ul>
-  );
-};
-
-export const ResponseExamples: React.FC<{
+interface ResponseExamplesProps {
   responseExamples: any;
   mimeType: string;
-}> = ({ responseExamples, mimeType }): any => {
+}
+export const ResponseExamples: React.FC<ResponseExamplesProps> = ({
+  responseExamples,
+  mimeType,
+}): any => {
   let language = "shell";
   if (mimeType.endsWith("json")) language = "json";
   if (mimeType.endsWith("xml")) language = "xml";
@@ -182,9 +74,9 @@ export const ResponseExamples: React.FC<{
         // @ts-ignore
         <TabItem label={exampleName} value={exampleName} key={exampleName}>
           {exampleValue.summary && (
-            <div className="openapi-example__summary">
+            <Markdown className="openapi-example__summary">
               {exampleValue.summary}
-            </div>
+            </Markdown>
           )}
           <ResponseSamples
             responseExample={responseExample}
@@ -198,10 +90,15 @@ export const ResponseExamples: React.FC<{
   return examplesArray;
 };
 
-export const ResponseExample: React.FC<{
+interface ResponseExampleProps {
   responseExample: any;
   mimeType: string;
-}> = ({ responseExample, mimeType }) => {
+}
+
+export const ResponseExample: React.FC<ResponseExampleProps> = ({
+  responseExample,
+  mimeType,
+}) => {
   let language = "shell";
   if (mimeType.endsWith("json")) {
     language = "json";
@@ -219,16 +116,21 @@ export const ResponseExample: React.FC<{
     // @ts-ignore
     <TabItem label="Example" value="Example">
       {responseExample.summary && (
-        <div className="openapi-example__summary">
+        <Markdown className="openapi-example__summary">
           {responseExample.summary}
-        </div>
+        </Markdown>
       )}
       <ResponseSamples responseExample={exampleContent} language={language} />
     </TabItem>
   );
 };
 
-export const ExampleFromSchema: React.FC<{ schema: any; mimeType: string }> = ({
+interface ExampleFromSchemaProps {
+  schema: any;
+  mimeType: string;
+}
+
+export const ExampleFromSchema: React.FC<ExampleFromSchemaProps> = ({
   schema,
   mimeType,
 }) => {