Fix support for example summaries (#898)

* switch from markdown to div for example summary * remove Markdown import from api page template * add examples for testing * add openapi-example__summary class
PaloAltoNetworks · Jul 23, 2024 · 6c12cd7 · 6c12cd7
1 parent a051895
commit 6c12cd7
Show file tree

Hide file tree

Showing 4 changed files with 17 additions and 12 deletions.
diff --git a/demo/examples/petstore.yaml b/demo/examples/petstore.yaml
@@ -909,6 +909,8 @@ paths:
                 type: string
               examples:
                 response:
+                  summary: |
+                    This is an example of using **Docusaurus** `markdown` in a summary. Note that admonitions are not fully supported.
                   value: OK
             application/xml:
               schema:
@@ -1194,6 +1196,7 @@ components:
                 title: Pettie
               - $ref: "#/components/schemas/Pet"
           example:
+            summary: A great example!
             category:
               name: Great Dane
               sub:

diff --git a/packages/docusaurus-plugin-openapi-docs/src/markdown/createStatusCodes.ts b/packages/docusaurus-plugin-openapi-docs/src/markdown/createStatusCodes.ts
@@ -127,8 +127,9 @@ export function createResponseExamples(
           value: `${exampleName}`,
           children: [
             guard(exampleValue.summary, (summary) => [
-              create("Markdown", {
-                children: ` ${summary}`,
+              create("div", {
+                children: `${summary}`,
+                className: "openapi-example__summary",
               }),
             ]),
             create("ResponseSamples", {
@@ -143,8 +144,9 @@ export function createResponseExamples(
         value: `${exampleName}`,
         children: [
           guard(exampleValue.summary, (summary) => [
-            create("Markdown", {
-              children: ` ${summary}`,
+            create("div", {
+              children: `${summary}`,
+              className: "openapi-example__summary",
             }),
           ]),
           create("ResponseSamples", {
@@ -171,8 +173,9 @@ export function createResponseExample(responseExample: any, mimeType: string) {
       value: `Example`,
       children: [
         guard(responseExample.summary, (summary) => [
-          create("Markdown", {
-            children: ` ${summary}`,
+          create("div", {
+            children: `${summary}`,
+            className: "openapi-example__summary",
           }),
         ]),
         create("ResponseSamples", {
@@ -187,8 +190,9 @@ export function createResponseExample(responseExample: any, mimeType: string) {
     value: `Example`,
     children: [
       guard(responseExample.summary, (summary) => [
-        create("Markdown", {
-          children: ` ${summary}`,
+        create("div", {
+          children: `${summary}`,
+          className: "openapi-example__summary",
         }),
       ]),
       create("ResponseSamples", {

diff --git a/packages/docusaurus-plugin-openapi-docs/src/markdown/index.ts b/packages/docusaurus-plugin-openapi-docs/src/markdown/index.ts
@@ -76,7 +76,6 @@ 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 Heading from "@theme/Heading";\n`,
     `import OperationTabs from "@theme/OperationTabs";\n`,
     `import TabItem from "@theme/TabItem";\n\n`,

diff --git a/packages/docusaurus-theme-openapi-docs/src/theme/ApiExplorer/Body/index.tsx b/packages/docusaurus-theme-openapi-docs/src/theme/ApiExplorer/Body/index.tsx
@@ -14,7 +14,6 @@ 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";
@@ -304,7 +303,7 @@ function Body({
           </TabItem>
           {/* @ts-ignore */}
           <TabItem label="Example" value="example">
-            {example.summary && <Markdown children={example.summary} />}
+            {example.summary && <div>{example.summary}</div>}
             {exampleBody && (
               <LiveApp
                 action={dispatch}
@@ -342,7 +341,7 @@ function Body({
                 value={example.label}
                 key={example.label}
               >
-                {example.summary && <Markdown children={example.summary} />}
+                {example.summary && <div>{example.summary}</div>}
                 {example.body && (
                   <LiveApp action={dispatch} language={language}>
                     {example.body}