docusaurus-theme-openapi-docs 4.2.0 → 4.3.0

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,
 }) => {

package/src/theme/ResponseHeaders/index.tsx

@@ -0,0 +1,49 @@
+/* ============================================================================
+ * 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 SchemaItem from "@theme/SchemaItem";
+
+import { getQualifierMessage, getSchemaName } from "../../markdown/schema";
+
+interface ResponseHeadersProps {
+  description?: string;
+  example?: string;
+  schema?: {
+    type?: string;
+    format?: string;
+  };
+}
+
+export const ResponseHeaders: React.FC<{
+  responseHeaders?: Record<string, ResponseHeadersProps>;
+}> = ({ responseHeaders }) => {
+  if (!responseHeaders) {
+    return null;
+  }
+
+  return (
+    <ul style={{ marginLeft: "1rem" }}>
+      {Object.entries(responseHeaders).map(([name, schema]) => {
+        return (
+          <SchemaItem
+            name={name}
+            collapsible={false}
+            schemaName={getSchemaName(schema)}
+            qualifierMessage={getQualifierMessage(schema)}
+            schema={schema}
+            discriminator={false}
+            children={null}
+          />
+        );
+      })}
+    </ul>
+  );
+};
+
+export default ResponseHeaders;

package/src/theme/ResponseSchema/index.tsx

@@ -9,6 +9,7 @@ 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 {
   ExampleFromSchema,
@@ -19,7 +20,6 @@ import SchemaNode from "@theme/Schema";
 import SchemaTabs from "@theme/SchemaTabs";
 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 {
@@ -99,7 +99,7 @@ const ResponseSchemaComponent: React.FC<Props> = ({
                           <div
                             style={{ marginTop: "1rem", marginBottom: "1rem" }}
                           >
-                            {createDescription(body.description)}
+                            <Markdown>{body.description}</Markdown>
                           </div>
                         )}
                       </div>

package/src/theme/Schema/index.tsx

@@ -10,21 +10,19 @@ import React from "react";
 import { ClosingArrayBracket, OpeningArrayBracket } from "@theme/ArrayBrackets";
 import Details from "@theme/Details";
 import DiscriminatorTabs from "@theme/DiscriminatorTabs";
+import Markdown from "@theme/Markdown";
 import SchemaItem from "@theme/SchemaItem";
 import SchemaTabs from "@theme/SchemaTabs";
 import TabItem from "@theme/TabItem";
 // eslint-disable-next-line import/no-extraneous-dependencies
 import { merge } from "allof-merge";
 import clsx from "clsx";
-import { createDescription } from "docusaurus-plugin-openapi-docs/lib/markdown/createDescription";
 import {
   getQualifierMessage,
   getSchemaName,
 } from "docusaurus-plugin-openapi-docs/lib/markdown/schema";
 import { SchemaObject } from "docusaurus-plugin-openapi-docs/lib/openapi/types";
 import isEmpty from "lodash/isEmpty";
-import ReactMarkdown from "react-markdown";
-import rehypeRaw from "rehype-raw";
 
 // eslint-disable-next-line import/no-extraneous-dependencies
 // const jsonSchemaMergeAllOf = require("json-schema-merge-allof");
@@ -44,13 +42,10 @@ interface MarkdownProps {
 }
 
 // Renders string as markdown, useful for descriptions and qualifiers
-const Markdown: React.FC<MarkdownProps> = ({ text }) => {
+const MarkdownWrapper: React.FC<MarkdownProps> = ({ text }) => {
   return (
     <div style={{ marginTop: ".5rem", marginBottom: ".5rem" }}>
-      <ReactMarkdown
-        children={createDescription(text)}
-        rehypePlugins={[rehypeRaw]}
-      />
+      <Markdown>{text}</Markdown>
     </div>
   );
 };
@@ -262,9 +257,11 @@ const PropertyDiscriminator: React.FC<SchemaEdgeProps> = ({
             )}
           </span>
           <div style={{ marginLeft: "1rem" }}>
-            {schema.description && <Markdown text={schema.description} />}
+            {schema.description && (
+              <MarkdownWrapper text={schema.description} />
+            )}
             {getQualifierMessage(discriminator) && (
-              <Markdown text={getQualifierMessage(discriminator)} />
+              <MarkdownWrapper text={getQualifierMessage(discriminator)} />
             )}
           </div>
           <DiscriminatorTabs className="openapi-tabs__discriminator">
@@ -320,7 +317,10 @@ const DiscriminatorNode: React.FC<DiscriminatorNodeProps> = ({
   let discriminatedSchemas: any = {};
   let inferredMapping: any = {};
 
-  const discriminatorProperty = schema.properties![discriminator.propertyName];
+  // default to empty object if no parent-level properties exist
+  const discriminatorProperty = schema.properties
+    ? schema.properties![discriminator.propertyName]
+    : {};
 
   if (schema.allOf) {
     const mergedSchemas = mergeAllOf(schema) as SchemaObject;
@@ -353,21 +353,28 @@ const DiscriminatorNode: React.FC<DiscriminatorNodeProps> = ({
 
     const subProperties = subSchema.properties || mergedSubSchema.properties;
     if (subProperties[discriminator.propertyName]) {
-      schema.properties![discriminator.propertyName] = {
-        ...schema.properties![discriminator.propertyName],
-        ...subProperties[discriminator.propertyName],
-      };
-      if (subSchema.required && !schema.required) {
-        schema.required = subSchema.required;
+      if (schema.properties) {
+        schema.properties![discriminator.propertyName] = {
+          ...schema.properties![discriminator.propertyName],
+          ...subProperties[discriminator.propertyName],
+        };
+        if (subSchema.required && !schema.required) {
+          schema.required = subSchema.required;
+        }
+        // Avoid duplicating property
+        delete subProperties[discriminator.propertyName];
+      } else {
+        schema.properties = {};
+        schema.properties[discriminator.propertyName] =
+          subProperties[discriminator.propertyName];
+        // Avoid duplicating property
+        delete subProperties[discriminator.propertyName];
       }
-      // Avoid duplicating property
-      delete subProperties[discriminator.propertyName];
     }
   });
 
   const name = discriminator.propertyName;
   const schemaName = getSchemaName(discriminatorProperty);
-
   // Default case for discriminator without oneOf/anyOf/allOf
   return (
     <PropertyDiscriminator
@@ -480,9 +487,9 @@ const SchemaNodeDetails: React.FC<SchemaEdgeProps> = ({
         }
       >
         <div style={{ marginLeft: "1rem" }}>
-          {schema.description && <Markdown text={schema.description} />}
+          {schema.description && <MarkdownWrapper text={schema.description} />}
           {getQualifierMessage(schema) && (
-            <Markdown text={getQualifierMessage(schema)} />
+            <MarkdownWrapper text={getQualifierMessage(schema)} />
           )}
           <SchemaNode schema={schema} schemaType={schemaType} />
         </div>

package/src/theme/SchemaItem/index.tsx

@@ -7,13 +7,9 @@
 
 import React, { ReactNode } from "react";
 
-import CodeBlock from "@theme/CodeBlock";
+import Markdown from "@theme/Markdown";
 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 { guard } from "../../markdown/utils";
 
 export interface Props {
@@ -97,44 +93,22 @@ export default function SchemaItem(props: Props) {
     (value) => {
       return (
         <div style={{ marginTop: ".5rem" }}>
-          <ReactMarkdown
-            remarkPlugins={[remarkGfm]}
-            rehypePlugins={[rehypeRaw]}
-            children={value}
-          />
+          <Markdown>{value}</Markdown>
         </div>
       );
     }
   );
 
   const renderSchemaDescription = guard(schemaDescription, (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 renderQualifierMessage = guard(qualifierMessage, (message) => (
-    <div>
-      <ReactMarkdown
-        children={createDescription(message)}
-        rehypePlugins={[rehypeRaw]}
-      />
-    </div>
+    <>
+      <Markdown>{message}</Markdown>
+    </>
   ));
 
   function renderDefaultValue() {
@@ -195,7 +169,9 @@ export default function SchemaItem(props: Props) {
         >
           {name}
         </strong>
-        <span className="openapi-schema__name"> {schemaName}</span>
+        <span className="openapi-schema__name">
+          {Array.isArray(schemaName) ? schemaName.join(" | ") : schemaName}
+        </span>
         {(nullable || required || deprecated) && (
           <span className="openapi-schema__divider"></span>
         )}

package/src/theme/StatusCodes/index.tsx

@@ -9,10 +9,10 @@ import React from "react";
 
 import ApiTabs from "@theme/ApiTabs";
 import Details from "@theme/Details";
-import { ResponseHeaders } from "@theme/ResponseExamples";
+import Markdown from "@theme/Markdown";
+import ResponseHeaders from "@theme/ResponseHeaders";
 import ResponseSchema from "@theme/ResponseSchema";
 import TabItem from "@theme/TabItem";
-import { createDescription } from "docusaurus-plugin-openapi-docs/lib/markdown/createDescription";
 import { ApiItem } from "docusaurus-plugin-openapi-docs/lib/types";
 
 interface Props {
@@ -39,7 +39,7 @@ const StatusCodes: React.FC<Props> = ({ label, id, responses }: any) => {
             <div>
               {response.description && (
                 <div style={{ marginTop: ".5rem", marginBottom: ".5rem" }}>
-                  {createDescription(response.description)}
+                  <Markdown>{response.description}</Markdown>
                 </div>
               )}
             </div>