docusaurus-theme-openapi-docs 4.0.1 → 4.2.0

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

@@ -14,6 +14,7 @@ import TabItem from "@theme/TabItem";
 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";
@@ -31,6 +32,7 @@ export interface ExampleObject {
 }
 
 export interface Props {
+  className: string;
   param: {
     description: string;
     example: any;
@@ -39,15 +41,49 @@ export interface Props {
     required: boolean;
     deprecated: boolean;
     schema: any;
+    enumDescriptions?: [string, string][];
   };
 }
 
-function ParamsItem({
-  param: { description, example, examples, name, required, schema, deprecated },
-}: Props) {
+const getEnumDescriptionMarkdown = (enumDescriptions?: [string, string][]) => {
+  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 }: Props) {
+  const {
+    description,
+    example,
+    examples,
+    name,
+    required,
+    deprecated,
+    enumDescriptions,
+  } = param;
+
+  let schema = param.schema;
+  let defaultValue: string | undefined;
+
   if (!schema || !schema?.type) {
     schema = { type: "any" };
   }
+  if (schema) {
+    if (schema.items) {
+      defaultValue = schema.items.default;
+    } else {
+      defaultValue = schema.default;
+    }
+  }
 
   const renderSchemaName = guard(schema, (schema) => (
     <span className="openapi-schema__type"> {getSchemaName(schema)}</span>
@@ -71,7 +107,7 @@ function ParamsItem({
   ));
 
   const renderDescription = guard(description, (description) => (
-    <div>
+    <>
       <ReactMarkdown
         children={createDescription(description)}
         components={{
@@ -88,22 +124,48 @@ function ParamsItem({
         }}
         rehypePlugins={[rehypeRaw]}
       />
-    </div>
+    </>
   ));
 
-  const renderDefaultValue = guard(
-    schema && schema.items
-      ? schema.items.default
-      : schema
-        ? schema.default
-        : undefined,
-    (value) => (
-      <div>
-        <ReactMarkdown children={`**Default value:** \`${value}\``} />
-      </div>
-    )
+  const renderEnumDescriptions = guard(
+    getEnumDescriptionMarkdown(enumDescriptions),
+    (value) => {
+      return (
+        <div style={{ marginTop: ".5rem" }}>
+          <ReactMarkdown
+            rehypePlugins={[rehypeRaw]}
+            remarkPlugins={[remarkGfm]}
+            children={value}
+          />
+        </div>
+      );
+    }
   );
 
+  function renderDefaultValue() {
+    if (defaultValue !== undefined) {
+      if (typeof defaultValue === "string") {
+        return (
+          <div>
+            <strong>Default value: </strong>
+            <span>
+              <code>{defaultValue}</code>
+            </span>
+          </div>
+        );
+      }
+      return (
+        <div>
+          <strong>Default value: </strong>
+          <span>
+            <code>{JSON.stringify(defaultValue)}</code>
+          </span>
+        </div>
+      );
+    }
+    return undefined;
+  }
+
   const renderExample = guard(toString(example), (example) => (
     <div>
       <strong>Example: </strong>
@@ -156,8 +218,9 @@ function ParamsItem({
         {renderDeprecated}
       </span>
       {renderSchema}
-      {renderDefaultValue}
       {renderDescription}
+      {renderEnumDescriptions}
+      {renderDefaultValue()}
       {renderExample}
       {renderExamples}
     </div>

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 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 {
+  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" }}>
+                      {createDescription(body.description)}
+                    </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" }}>
+                {createDescription(body.description)}
+              </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;

package/src/theme/ResponseExamples/index.tsx

@@ -0,0 +1,290 @@
+/* ============================================================================
+ * 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 from "react";
+
+import ParamsItem from "@theme/ParamsItem";
+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 = "";
+    if (v instanceof Array) {
+      for (let i = 0, n = v.length; i < n; i++) {
+        xml += ind + toXml(v[i], name, ind + "\t") + "\n";
+      }
+    } else if (typeof v === "object") {
+      let hasChild = false;
+      xml += ind + "<" + name;
+      for (const m in v) {
+        if (m.charAt(0) === "@") {
+          xml += " " + m.substr(1) + '="' + v[m].toString() + '"';
+        } else {
+          hasChild = true;
+        }
+      }
+      xml += hasChild ? ">" : "/>";
+      if (hasChild) {
+        for (const m2 in v) {
+          if (m2 === "#text") xml += v[m2];
+          else if (m2 === "#cdata") xml += "<![CDATA[" + v[m2] + "]]>";
+          else if (m2.charAt(0) !== "@") xml += toXml(v[m2], m2, ind + "\t");
+        }
+        xml +=
+          (xml.charAt(xml.length - 1) === "\n" ? ind : "") + "</" + name + ">";
+      }
+    } else {
+      xml += ind + "<" + name + ">" + v.toString() + "</" + name + ">";
+    }
+    return xml;
+  };
+  let xml = "";
+  for (const m3 in o) xml += toXml(o[m3], m3, "");
+  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<{
+  responseExamples: any;
+  mimeType: string;
+}> = ({ responseExamples, mimeType }): any => {
+  let language = "shell";
+  if (mimeType.endsWith("json")) language = "json";
+  if (mimeType.endsWith("xml")) language = "xml";
+
+  // Map response examples to an array of TabItem elements
+  const examplesArray = Object.entries(responseExamples).map(
+    ([exampleName, exampleValue]: any) => {
+      const isObject = typeof exampleValue.value === "object";
+      const responseExample = isObject
+        ? JSON.stringify(exampleValue.value, null, 2)
+        : exampleValue.value;
+
+      return (
+        // @ts-ignore
+        <TabItem label={exampleName} value={exampleName} key={exampleName}>
+          {exampleValue.summary && (
+            <div className="openapi-example__summary">
+              {exampleValue.summary}
+            </div>
+          )}
+          <ResponseSamples
+            responseExample={responseExample}
+            language={language}
+          />
+        </TabItem>
+      );
+    }
+  );
+
+  return examplesArray;
+};
+
+export const ResponseExample: React.FC<{
+  responseExample: any;
+  mimeType: string;
+}> = ({ responseExample, mimeType }) => {
+  let language = "shell";
+  if (mimeType.endsWith("json")) {
+    language = "json";
+  }
+  if (mimeType.endsWith("xml")) {
+    language = "xml";
+  }
+
+  const isObject = typeof responseExample === "object";
+  const exampleContent = isObject
+    ? JSON.stringify(responseExample, null, 2)
+    : responseExample;
+
+  return (
+    // @ts-ignore
+    <TabItem label="Example" value="Example">
+      {responseExample.summary && (
+        <div className="openapi-example__summary">
+          {responseExample.summary}
+        </div>
+      )}
+      <ResponseSamples responseExample={exampleContent} language={language} />
+    </TabItem>
+  );
+};
+
+export const ExampleFromSchema: React.FC<{ schema: any; mimeType: string }> = ({
+  schema,
+  mimeType,
+}) => {
+  const responseExample = sampleResponseFromSchema(schema);
+
+  if (mimeType.endsWith("xml")) {
+    let responseExampleObject;
+    try {
+      responseExampleObject = JSON.parse(JSON.stringify(responseExample));
+    } catch {
+      return null;
+    }
+
+    if (typeof responseExampleObject === "object") {
+      let xmlExample;
+      try {
+        xmlExample = format(json2xml(responseExampleObject, ""), {
+          indentation: "  ",
+          lineSeparator: "\n",
+          collapseContent: true,
+        });
+      } catch {
+        const xmlExampleWithRoot = { root: responseExampleObject };
+        try {
+          xmlExample = format(json2xml(xmlExampleWithRoot, ""), {
+            indentation: "  ",
+            lineSeparator: "\n",
+            collapseContent: true,
+          });
+        } catch {
+          xmlExample = json2xml(responseExampleObject, "");
+        }
+      }
+      return (
+        // @ts-ignore
+        <TabItem label="Example (auto)" value="Example (auto)">
+          <ResponseSamples responseExample={xmlExample} language="xml" />
+        </TabItem>
+      );
+    }
+  }
+
+  if (
+    typeof responseExample === "object" ||
+    typeof responseExample === "string"
+  ) {
+    return (
+      // @ts-ignore
+      <TabItem label="Example (auto)" value="Example (auto)">
+        <ResponseSamples
+          responseExample={JSON.stringify(responseExample, null, 2)}
+          language="json"
+        />
+      </TabItem>
+    );
+  }
+
+  return null;
+};