Add markdown support to example summary (#690)

* Add Markdown import to api doc generator

* support markdown rendering for example summary

* add markdown component

* install missing eslint package

* fix import order

* update lock file

package.json

@@ -41,6 +41,7 @@
   },
   "devDependencies": {
     "@babel/core": "^7.16.0",
+    "@eslint-community/eslint-utils": "^4.4.0",
     "@testing-library/cypress": "^8.0.1",
     "@types/jest": "^27.0.2",
     "@types/node": "^17.0.2",

packages/docusaurus-plugin-openapi-docs/src/markdown/createStatusCodes.ts

@@ -127,7 +127,7 @@ export function createResponseExamples(
           value: `${exampleName}`,
           children: [
             guard(exampleValue.summary, (summary) => [
-              create("p", {
+              create("Markdown", {
                 children: ` ${summary}`,
               }),
             ]),
@@ -143,7 +143,7 @@ export function createResponseExamples(
         value: `${exampleName}`,
         children: [
           guard(exampleValue.summary, (summary) => [
-            create("p", {
+            create("Markdown", {
               children: ` ${summary}`,
             }),
           ]),
@@ -171,7 +171,7 @@ export function createResponseExample(responseExample: any, mimeType: string) {
       value: `Example`,
       children: [
         guard(responseExample.summary, (summary) => [
-          create("p", {
+          create("Markdown", {
             children: ` ${summary}`,
           }),
         ]),
@@ -187,7 +187,7 @@ export function createResponseExample(responseExample: any, mimeType: string) {
     value: `Example`,
     children: [
       guard(responseExample.summary, (summary) => [
-        create("p", {
+        create("Markdown", {
           children: ` ${summary}`,
         }),
       ]),

packages/docusaurus-plugin-openapi-docs/src/markdown/index.ts

@@ -70,6 +70,7 @@ export function createApiPageMD({
     `import ResponseSamples from "@theme/ResponseSamples";\n`,
     `import SchemaItem from "@theme/SchemaItem";\n`,
     `import SchemaTabs from "@theme/SchemaTabs";\n`,
+    `import Markdown from "@theme/Markdown";\n`,
     `import OperationTabs from "@theme/OperationTabs";\n`,
     `import TabItem from "@theme/TabItem";\n\n`,
     createHeading(title.replace(lessThan, "<").replace(greaterThan, ">")),

packages/docusaurus-theme-openapi-docs/src/theme-openapi.d.ts

@@ -63,6 +63,10 @@ declare module "@theme/SchemaTabs" {
   export default function SchemaTabs(props: any): JSX.Element;
 }
 
+declare module "@theme/Markdown" {
+  export default function Markdown(props: any): JSX.Element;
+}
+
 declare module "@theme/ApiExplorer/Accept" {
   export default function Accept(): JSX.Element;
 }

packages/docusaurus-theme-openapi-docs/src/theme/ApiExplorer/Body/index.tsx

@@ -14,6 +14,7 @@ import FormSelect from "@theme/ApiExplorer/FormSelect";
 import FormTextInput from "@theme/ApiExplorer/FormTextInput";
 import LiveApp from "@theme/ApiExplorer/LiveEditor";
 import { useTypedDispatch, useTypedSelector } from "@theme/ApiItem/hooks";
+import Markdown from "@theme/Markdown";
 import SchemaTabs from "@theme/SchemaTabs";
 import TabItem from "@theme/TabItem";
 import { RequestBodyObject } from "docusaurus-plugin-openapi-docs/src/openapi/types";
@@ -303,6 +304,7 @@ function Body({
           </TabItem>
           {/* @ts-ignore */}
           <TabItem label="Example" value="example">
+            {example.summary && <Markdown children={example.summary} />}
             {exampleBody && (
               <LiveApp
                 action={dispatch}
@@ -340,7 +342,7 @@ function Body({
                 value={example.label}
                 key={example.label}
               >
-                {example.summary && <p>{example.summary}</p>}
+                {example.summary && <Markdown children={example.summary} />}
                 {example.body && (
                   <LiveApp action={dispatch} language={language}>
                     {example.body}

packages/docusaurus-theme-openapi-docs/src/theme/Markdown/index.js

@@ -0,0 +1,37 @@
+/* ============================================================================
+ * 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 CodeBlock from "@theme/CodeBlock";
+import ReactMarkdown from "react-markdown";
+import rehypeRaw from "rehype-raw";
+
+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>
+  );
+}
+
+export default Markdown;

yarn.lock

@@ -1675,6 +1675,13 @@
     url-loader "^4.1.1"
     webpack "^5.73.0"
 
+"@eslint-community/eslint-utils@^4.4.0":
+  version "4.4.0"
+  resolved "https://registry.yarnpkg.com/@eslint-community/eslint-utils/-/eslint-utils-4.4.0.tgz#a23514e8fb9af1269d5f7788aa556798d61c6b59"
+  integrity sha512-1/sA4dwrzBAyeUoQ6oxahHKmrZvsnLCg4RfxW3ZFGGmQkSNQPFNLV9CUEFQP1x9EYXHTo5p6xdhZM1Ne9p/AfA==
+  dependencies:
+    eslint-visitor-keys "^3.3.0"
+
 "@eslint/eslintrc@^0.4.3":
   version "0.4.3"
   resolved "https://registry.yarnpkg.com/@eslint/eslintrc/-/eslintrc-0.4.3.tgz#9e42981ef035beb3dd49add17acb96e8ff6f394c"