Skip to content

Commit 10dd3c3

Browse files
committed
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
1 parent 50a0702 commit 10dd3c3

File tree

7 files changed

+57
-5
lines changed

7 files changed

+57
-5
lines changed

package.json

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -41,6 +41,7 @@
4141
},
4242
"devDependencies": {
4343
"@babel/core": "^7.16.0",
44+
"@eslint-community/eslint-utils": "^4.4.0",
4445
"@testing-library/cypress": "^8.0.1",
4546
"@types/jest": "^27.0.2",
4647
"@types/node": "^17.0.2",

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

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -127,7 +127,7 @@ export function createResponseExamples(
127127
value: `${exampleName}`,
128128
children: [
129129
guard(exampleValue.summary, (summary) => [
130-
create("p", {
130+
create("Markdown", {
131131
children: ` ${summary}`,
132132
}),
133133
]),
@@ -143,7 +143,7 @@ export function createResponseExamples(
143143
value: `${exampleName}`,
144144
children: [
145145
guard(exampleValue.summary, (summary) => [
146-
create("p", {
146+
create("Markdown", {
147147
children: ` ${summary}`,
148148
}),
149149
]),
@@ -171,7 +171,7 @@ export function createResponseExample(responseExample: any, mimeType: string) {
171171
value: `Example`,
172172
children: [
173173
guard(responseExample.summary, (summary) => [
174-
create("p", {
174+
create("Markdown", {
175175
children: ` ${summary}`,
176176
}),
177177
]),
@@ -187,7 +187,7 @@ export function createResponseExample(responseExample: any, mimeType: string) {
187187
value: `Example`,
188188
children: [
189189
guard(responseExample.summary, (summary) => [
190-
create("p", {
190+
create("Markdown", {
191191
children: ` ${summary}`,
192192
}),
193193
]),

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

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -70,6 +70,7 @@ export function createApiPageMD({
7070
`import ResponseSamples from "@theme/ResponseSamples";\n`,
7171
`import SchemaItem from "@theme/SchemaItem";\n`,
7272
`import SchemaTabs from "@theme/SchemaTabs";\n`,
73+
`import Markdown from "@theme/Markdown";\n`,
7374
`import OperationTabs from "@theme/OperationTabs";\n`,
7475
`import TabItem from "@theme/TabItem";\n\n`,
7576
createHeading(title),

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

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -65,6 +65,10 @@ declare module "@theme/SchemaTabs" {
6565
export default function SchemaTabs(props: any): JSX.Element;
6666
}
6767

68+
declare module "@theme/Markdown" {
69+
export default function Markdown(props: any): JSX.Element;
70+
}
71+
6872
declare module "@theme/ApiExplorer/Accept" {
6973
export default function Accept(): JSX.Element;
7074
}

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

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@ import FormSelect from "@theme/ApiExplorer/FormSelect";
1414
import FormTextInput from "@theme/ApiExplorer/FormTextInput";
1515
import LiveApp from "@theme/ApiExplorer/LiveEditor";
1616
import { useTypedDispatch, useTypedSelector } from "@theme/ApiItem/hooks";
17+
import Markdown from "@theme/Markdown";
1718
import SchemaTabs from "@theme/SchemaTabs";
1819
import TabItem from "@theme/TabItem";
1920
import { RequestBodyObject } from "docusaurus-plugin-openapi-docs/src/openapi/types";
@@ -303,6 +304,7 @@ function Body({
303304
</TabItem>
304305
{/* @ts-ignore */}
305306
<TabItem label="Example" value="example">
307+
{example.summary && <Markdown children={example.summary} />}
306308
{exampleBody && (
307309
<LiveApp
308310
action={dispatch}
@@ -340,7 +342,7 @@ function Body({
340342
value={example.label}
341343
key={example.label}
342344
>
343-
{example.summary && <p>{example.summary}</p>}
345+
{example.summary && <Markdown children={example.summary} />}
344346
{example.body && (
345347
<LiveApp action={dispatch} language={language}>
346348
{example.body}
Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
/* ============================================================================
2+
* Copyright (c) Palo Alto Networks
3+
*
4+
* This source code is licensed under the MIT license found in the
5+
* LICENSE file in the root directory of this source tree.
6+
* ========================================================================== */
7+
8+
import React from "react";
9+
10+
import CodeBlock from "@theme/CodeBlock";
11+
import ReactMarkdown from "react-markdown";
12+
import rehypeRaw from "rehype-raw";
13+
14+
function Markdown({ children }) {
15+
return (
16+
<div>
17+
<ReactMarkdown
18+
children={children}
19+
rehypePlugins={[rehypeRaw]}
20+
components={{
21+
pre: "div",
22+
code({ node, inline, className, children, ...props }) {
23+
const match = /language-(\w+)/.exec(className || "");
24+
if (inline) return <code>{children}</code>;
25+
return !inline && match ? (
26+
<CodeBlock className={className}>{children}</CodeBlock>
27+
) : (
28+
<CodeBlock>{children}</CodeBlock>
29+
);
30+
},
31+
}}
32+
/>
33+
</div>
34+
);
35+
}
36+
37+
export default Markdown;

yarn.lock

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1709,6 +1709,13 @@
17091709
resolved "https://registry.npmjs.org/@eslint-community/regexpp/-/regexpp-4.10.0.tgz#548f6de556857c8bb73bbee70c35dc82a2e74d63"
17101710
integrity sha512-Cu96Sd2By9mCNTx2iyKOmq10v22jUVQv0lQnlGNy16oE9589yE+QADPbrMGCkA51cKZSg3Pu/aTJVTGfL/qjUA==
17111711

1712+
"@eslint-community/eslint-utils@^4.4.0":
1713+
version "4.4.0"
1714+
resolved "https://registry.yarnpkg.com/@eslint-community/eslint-utils/-/eslint-utils-4.4.0.tgz#a23514e8fb9af1269d5f7788aa556798d61c6b59"
1715+
integrity sha512-1/sA4dwrzBAyeUoQ6oxahHKmrZvsnLCg4RfxW3ZFGGmQkSNQPFNLV9CUEFQP1x9EYXHTo5p6xdhZM1Ne9p/AfA==
1716+
dependencies:
1717+
eslint-visitor-keys "^3.3.0"
1718+
17121719
"@eslint/eslintrc@^0.4.3":
17131720
version "0.4.3"
17141721
resolved "https://registry.npmjs.org/@eslint/eslintrc/-/eslintrc-0.4.3.tgz#9e42981ef035beb3dd49add17acb96e8ff6f394c"

0 commit comments

Comments
 (0)