add markdownGenerators example and update docs

Author: sserrata

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", "<br/>");
+  })
+  .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 }),
+  ]);
+}

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.<br/><br/>**Function type:** `(pageData: TagPageMetadata) => string`       |
 | `createSchemaPageMD` | `function` | `null`  | _Optional:_ Returns a string of the raw markdown body for schema pages.<br/><br/>**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.

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",