diff --git a/demo/customMdGenerators.ts b/demo/customMdGenerators.ts
new file mode 100644
index 000000000..031abb2fd
--- /dev/null
+++ b/demo/customMdGenerators.ts
@@ -0,0 +1,79 @@
+import { createAuthorization } from "docusaurus-plugin-openapi-docs/lib/markdown/createAuthorization";
+import { createCallbacks } from "docusaurus-plugin-openapi-docs/lib/markdown/createCallbacks";
+import { createDeprecationNotice } from "docusaurus-plugin-openapi-docs/lib/markdown/createDeprecationNotice";
+import { createDescription } from "docusaurus-plugin-openapi-docs/lib/markdown/createDescription";
+import { createHeading } from "docusaurus-plugin-openapi-docs/lib/markdown/createHeading";
+import { createMethodEndpoint } from "docusaurus-plugin-openapi-docs/lib/markdown/createMethodEndpoint";
+import { createParamsDetails } from "docusaurus-plugin-openapi-docs/lib/markdown/createParamsDetails";
+import { createRequestBodyDetails } from "docusaurus-plugin-openapi-docs/lib/markdown/createRequestBodyDetails";
+import { createRequestHeader } from "docusaurus-plugin-openapi-docs/lib/markdown/createRequestHeader";
+import { createStatusCodes } from "docusaurus-plugin-openapi-docs/lib/markdown/createStatusCodes";
+import { createVendorExtensions } from "docusaurus-plugin-openapi-docs/lib/markdown/createVendorExtensions";
+import { render } from "docusaurus-plugin-openapi-docs/lib/markdown/utils";
+
+function createServersTable(servers: any[]) {
+ if (servers.length) {
+ return `| URL | Description |
+| ---- | ----- |
+${servers
+ .map((server) => {
+ return `| ${server.url} | ${server.description} | `.replace("\n", "
");
+ })
+ .join("\n")}
+ `;
+ }
+}
+
+export function myCustomApiMdGenerator({
+ title,
+ api: {
+ deprecated,
+ "x-deprecated-description": deprecatedDescription,
+ description,
+ method,
+ path,
+ extensions,
+ parameters,
+ requestBody,
+ responses,
+ callbacks,
+ servers, // destructure servers here
+ },
+ infoPath,
+ frontMatter,
+}: ApiPageMetadata) {
+ return render([
+ `import ApiTabs from "@theme/ApiTabs";\n`,
+ `import DiscriminatorTabs from "@theme/DiscriminatorTabs";\n`,
+ `import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";\n`,
+ `import SecuritySchemes from "@theme/ApiExplorer/SecuritySchemes";\n`,
+ `import MimeTabs from "@theme/MimeTabs";\n`,
+ `import ParamsItem from "@theme/ParamsItem";\n`,
+ `import ResponseSamples from "@theme/ResponseSamples";\n`,
+ `import SchemaItem from "@theme/SchemaItem";\n`,
+ `import SchemaTabs from "@theme/SchemaTabs";\n`,
+ `import Heading from "@theme/Heading";\n`,
+ `import OperationTabs from "@theme/OperationTabs";\n`,
+ `import TabItem from "@theme/TabItem";\n\n`,
+ createHeading(title),
+ createMethodEndpoint(method, path),
+ createServersTable(servers),
+ infoPath && createAuthorization(infoPath),
+ frontMatter.show_extensions
+ ? createVendorExtensions(extensions)
+ : undefined,
+ createDeprecationNotice({ deprecated, description: deprecatedDescription }),
+ createDescription(description),
+ requestBody || parameters ? createRequestHeader("Request") : undefined,
+ createParamsDetails({ parameters, type: "path" }),
+ createParamsDetails({ parameters, type: "query" }),
+ createParamsDetails({ parameters, type: "header" }),
+ createParamsDetails({ parameters, type: "cookie" }),
+ createRequestBodyDetails({
+ title: "Body",
+ body: requestBody,
+ } as RequestBodyProps),
+ createStatusCodes({ responses }),
+ createCallbacks({ callbacks }),
+ ]);
+}
diff --git a/demo/docs/intro.mdx b/demo/docs/intro.mdx
index 9e9861c89..236051011 100644
--- a/demo/docs/intro.mdx
+++ b/demo/docs/intro.mdx
@@ -197,7 +197,7 @@ The `docusaurus-plugin-openapi-docs` plugin can be configured with the following
| `label` | `string` | `null` | _Optional:_ Version label used when generating version selector dropdown menu. |
| `baseUrl` | `string` | `null` | _Optional:_ Version base URL used when generating version selector dropdown menu. |
| `versions` | `object` | `null` | _Optional:_ Set of options for versioning configuration. See below for a list of supported options. |
-| `markdownGenerators` | `object` | `null` | _Optional:_ Customize MDX content with a set of options for specifying markdown generator functions. See below for a list of supported options. |
+| `markdownGenerators` | `object` | `null` | _Optional:_ Customize MDX content with a set of options for specifying markdown generator functions. See [markdownGenerators](#markdowngenerators) for a list of supported options. |
| `showSchemas` | `boolean` | `null` | _Optional:_ If set to `true`, generates schema pages and adds them to the sidebar. |
`sidebarOptions` can be configured with the following options:
@@ -234,6 +234,24 @@ The `docusaurus-plugin-openapi-docs` plugin can be configured with the following
| `createTagPageMD` | `function` | `null` | _Optional:_ Returns a string of the raw markdown body for tag pages.
**Function type:** `(pageData: TagPageMetadata) => string` |
| `createSchemaPageMD` | `function` | `null` | _Optional:_ Returns a string of the raw markdown body for schema pages.
**Function type:** `(pageData: SchemaPageMetadata) => string` |
+Example:
+
+```javascript
+petstore31: {
+ specPath: "examples/petstore-3.1.yaml",
+ proxy: "https://cors.pan.dev",
+ outputDir: "docs/petstore31",
+ sidebarOptions: {
+ groupPathsBy: "tag",
+ categoryLinkSource: "tag",
+ },
+ downloadUrl: "/petstore-3.1.yaml",
+ hideSendButton: false,
+ showSchemas: true,
+ markdownGenerators: { createApiPageMD: myCustomApiMdGenerator }, // customize MDX with markdown generator
+} satisfies OpenApiPlugin.Options,
+```
+
## CLI Usage
After you've installed and configured the plugin and theme, the CLI can be used to `generate` and `clean` API docs.
diff --git a/demo/docusaurus.config.ts b/demo/docusaurus.config.ts
index f28c8a5de..51faf4345 100644
--- a/demo/docusaurus.config.ts
+++ b/demo/docusaurus.config.ts
@@ -4,6 +4,7 @@ import type * as Plugin from "@docusaurus/types/src/plugin";
import type * as OpenApiPlugin from "docusaurus-plugin-openapi-docs";
import { DOCUSAURUS_VERSION } from "@docusaurus/utils";
+import { myCustomApiMdGenerator } from "./customMdGenerators";
const config: Config = {
title: "Docusaurus OpenAPI Docs",
@@ -305,10 +306,10 @@ const config: Config = {
groupPathsBy: "tag",
categoryLinkSource: "tag",
},
- template: "api.mustache", // Customize API MDX with mustache template
downloadUrl: "/petstore-3.1.yaml",
hideSendButton: false,
showSchemas: true,
+ markdownGenerators: { createApiPageMD: myCustomApiMdGenerator }, // customize MDX with markdown generator
} satisfies OpenApiPlugin.Options,
cos: {
specPath: "examples/openapi-cos.json",