docusaurus-plugin-openapi-docs 4.1.0 → 4.3.0

package/src/index.ts

@@ -21,18 +21,18 @@ import {
   createSchemaPageMD,
   createTagPageMD,
 } from "./markdown";
-import { readOpenapiFiles, processOpenapiFiles } from "./openapi";
+import { processOpenapiFiles, readOpenapiFiles } from "./openapi";
 import { OptionsSchema } from "./options";
 import generateSidebarSlice from "./sidebars";
 import type {
-  PluginOptions,
-  LoadedContent,
-  APIOptions,
   ApiMetadata,
+  APIOptions,
   ApiPageMetadata,
   InfoPageMetadata,
-  TagPageMetadata,
+  LoadedContent,
+  PluginOptions,
   SchemaPageMetadata,
+  TagPageMetadata,
 } from "./types";
 
 export function isURL(str: string): boolean {
@@ -278,7 +278,11 @@ title: "{{{title}}}"
 description: "{{{frontMatter.description}}}"
 sidebar_label: "{{{title}}}"
 hide_title: true
+{{#schema}}
+hide_table_of_contents: true
+{{/schema}}
 schema: true
+sample: {{{frontMatter.sample}}}
 custom_edit_url: null
 ---
 
@@ -582,6 +586,66 @@ custom_edit_url: null
     }
   }
 
+  async function generateAllVersions(options: APIOptions, pluginId: any) {
+    const parentOptions = Object.assign({}, options);
+    const { versions } = parentOptions as any;
+
+    if (versions != null && Object.keys(versions).length > 0) {
+      const version = parentOptions.version as string;
+      const label = parentOptions.label as string;
+
+      const baseUrl = parentOptions.baseUrl as string;
+      let parentVersion = {} as any;
+
+      parentVersion[version] = { label: label, baseUrl: baseUrl };
+      const mergedVersions = Object.assign(parentVersion, versions);
+
+      // Prepare for merge
+      delete parentOptions.versions;
+      delete parentOptions.version;
+      delete parentOptions.label;
+      delete parentOptions.baseUrl;
+      delete parentOptions.downloadUrl;
+
+      await generateVersions(mergedVersions, parentOptions.outputDir);
+      Object.keys(versions).forEach(async (key) => {
+        if (key === "all") {
+          console.error(
+            chalk.red(
+              "Can't use id 'all' for OpenAPI docs versions configuration key."
+            )
+          );
+        }
+        const versionOptions = versions[key];
+        const mergedOptions = {
+          ...parentOptions,
+          ...versionOptions,
+        };
+        await generateApiDocs(mergedOptions, pluginId);
+      });
+    }
+  }
+
+  async function cleanAllVersions(options: APIOptions) {
+    const parentOptions = Object.assign({}, options);
+
+    const { versions } = parentOptions as any;
+
+    delete parentOptions.versions;
+
+    if (versions != null && Object.keys(versions).length > 0) {
+      await cleanVersions(parentOptions.outputDir);
+      Object.keys(versions).forEach(async (key) => {
+        const versionOptions = versions[key];
+        const mergedOptions = {
+          ...parentOptions,
+          ...versionOptions,
+        };
+        await cleanApiDocs(mergedOptions);
+      });
+    }
+  }
+
   return {
     name: `docusaurus-plugin-openapi-docs`,
 
@@ -594,9 +658,11 @@ custom_edit_url: null
         .usage("<id>")
         .arguments("<id>")
         .option("-p, --plugin-id <plugin>", "OpenAPI docs plugin ID.")
+        .option("--all-versions", "Generate all versions.")
         .action(async (id, instance) => {
           const options = instance.opts();
           const pluginId = options.pluginId;
+          const allVersions = options.allVersions;
           const pluginInstances = getPluginInstances(plugins);
           let targetConfig: any;
           let targetDocsPluginId: any;
@@ -633,6 +699,12 @@ custom_edit_url: null
             } else {
               Object.keys(targetConfig).forEach(async function (key) {
                 await generateApiDocs(targetConfig[key], targetDocsPluginId);
+                if (allVersions) {
+                  await generateAllVersions(
+                    targetConfig[key],
+                    targetDocsPluginId
+                  );
+                }
               });
             }
           } else if (!targetConfig[id]) {
@@ -641,6 +713,9 @@ custom_edit_url: null
             );
           } else {
             await generateApiDocs(targetConfig[id], targetDocsPluginId);
+            if (allVersions) {
+              await generateAllVersions(targetConfig[id], targetDocsPluginId);
+            }
           }
         });
 
@@ -744,9 +819,11 @@ custom_edit_url: null
         .usage("<id>")
         .arguments("<id>")
         .option("-p, --plugin-id <plugin>", "OpenAPI docs plugin ID.")
+        .option("--all-versions", "Clean all versions.")
         .action(async (id, instance) => {
           const options = instance.opts();
           const pluginId = options.pluginId;
+          const allVersions = options.allVersions;
           const pluginInstances = getPluginInstances(plugins);
           let targetConfig: any;
           if (pluginId) {
@@ -780,10 +857,16 @@ custom_edit_url: null
             } else {
               Object.keys(targetConfig).forEach(async function (key) {
                 await cleanApiDocs(targetConfig[key]);
+                if (allVersions) {
+                  await cleanAllVersions(targetConfig[key]);
+                }
               });
             }
           } else {
             await cleanApiDocs(targetConfig[id]);
+            if (allVersions) {
+              await cleanAllVersions(targetConfig[id]);
+            }
           }
         });
 

package/src/markdown/__snapshots__/createSchema.test.ts.snap

@@ -364,6 +364,24 @@ Array [
   qualifierMessage={undefined}
   schema={{ type: \\"string\\" }}
 ></SchemaItem>;
+",
+  "<SchemaItem
+  collapsible={false}
+  name={\\"parentProp1\\"}
+  required={false}
+  schemaName={\\"string\\"}
+  qualifierMessage={undefined}
+  schema={{ type: \\"string\\" }}
+></SchemaItem>;
+",
+  "<SchemaItem
+  collapsible={false}
+  name={\\"parentProp2\\"}
+  required={false}
+  schemaName={\\"string\\"}
+  qualifierMessage={undefined}
+  schema={{ type: \\"string\\" }}
+></SchemaItem>;
 ",
 ]
 `;
@@ -711,6 +729,15 @@ Array [
   qualifierMessage={undefined}
   schema={{ type: \\"string\\" }}
 ></SchemaItem>;
+",
+  "<SchemaItem
+  collapsible={false}
+  name={\\"type\\"}
+  required={false}
+  schemaName={\\"string\\"}
+  qualifierMessage={undefined}
+  schema={{ type: \\"string\\" }}
+></SchemaItem>;
 ",
 ]
 `;
@@ -797,6 +824,34 @@ Array [
   qualifierMessage={undefined}
   schema={{ type: \\"string\\" }}
 ></SchemaItem>;
+",
+  "<div className={\\"openapi-discriminator__item openapi-schema__list-item\\"}>
+  <div>
+    <span className={\\"openapi-schema__container\\"}>
+      <strong
+        className={\\"openapi-discriminator__name openapi-schema__property\\"}
+      >
+        type
+      </strong>
+      <span className={\\"openapi-schema__name\\"}>string</span>
+    </span>
+    <div style={{ paddingLeft: \\"1rem\\" }}>
+      **Possible values:** [\`typeA\`, \`typeB\`]
+    </div>
+    <DiscriminatorTabs className={\\"openapi-tabs__discriminator\\"}>
+      <TabItem label={\\"typeA\\"} value={\\"0-item-discriminator\\"}>
+        <div style={{ marginTop: \\".5rem\\", marginBottom: \\".5rem\\" }}>
+          #/definitions/TypeA
+        </div>
+      </TabItem>
+      <TabItem label={\\"typeB\\"} value={\\"1-item-discriminator\\"}>
+        <div style={{ marginTop: \\".5rem\\", marginBottom: \\".5rem\\" }}>
+          #/definitions/TypeB
+        </div>
+      </TabItem>
+    </DiscriminatorTabs>
+  </div>
+</div>;
 ",
 ]
 `;

package/src/markdown/createAuthentication.ts

@@ -35,15 +35,15 @@ export function createAuthentication(securitySchemes: SecuritySchemeObject) {
             create("td", {
               children: [
                 guard(tokenUrl, () =>
-                  create("p", { children: `Token URL: ${tokenUrl}` })
+                  create("div", { children: `Token URL: ${tokenUrl}` })
                 ),
                 guard(authorizationUrl, () =>
-                  create("p", {
+                  create("div", {
                     children: `Authorization URL: ${authorizationUrl}`,
                   })
                 ),
                 guard(refreshUrl, () =>
-                  create("p", { children: `Refresh URL: ${refreshUrl}` })
+                  create("div", { children: `Refresh URL: ${refreshUrl}` })
                 ),
                 create("span", { children: "Scopes:" }),
                 create("ul", {

package/src/markdown/createContactInfo.ts

@@ -33,7 +33,7 @@ export function createContactInfo(contact: ContactObject) {
       }),
       guard(url, () =>
         create("span", {
-          children: ["URL: ", `[${url}](mailto:${url})`],
+          children: ["URL: ", `[${url}](${url})`],
         })
       ),
     ],

package/src/markdown/createParamsDetails.ts

@@ -5,60 +5,18 @@
  * LICENSE file in the root directory of this source tree.
  * ========================================================================== */
 
-import { createDetails } from "./createDetails";
-import { createDetailsSummary } from "./createDetailsSummary";
 import { create } from "./utils";
 import { ApiItem } from "../types";
 
 interface Props {
   parameters: ApiItem["parameters"];
-  type: "path" | "query" | "header" | "cookie";
 }
 
-export function createParamsDetails({ parameters, type }: Props) {
-  if (parameters === undefined) {
-    return undefined;
-  }
-  const params = parameters.filter((param) => param?.in === type);
-  if (params.length === 0) {
-    return undefined;
-  }
-
-  return createDetails({
-    className: "openapi-markdown__details",
-    "data-collapsed": false,
-    open: true,
-    style: { marginBottom: "1rem" },
-    children: [
-      createDetailsSummary({
-        children: [
-          create("h3", {
-            className: "openapi-markdown__details-summary-header-params",
-            children: `${
-              type.charAt(0).toUpperCase() + type.slice(1)
-            } Parameters`,
-          }),
-        ],
-      }),
-      create("div", {
-        children: [
-          create("ul", {
-            children: params.map((param) => {
-              return create("ParamsItem", {
-                className: "paramsItem",
-                param: {
-                  ...param,
-                  enumDescriptions: Object.entries(
-                    param?.schema?.["x-enumDescriptions"] ??
-                      param?.schema?.items?.["x-enumDescriptions"] ??
-                      {}
-                  ),
-                },
-              });
-            }),
-          }),
-        ],
-      }),
-    ],
-  });
+export function createParamsDetails({ parameters }: Props) {
+  return [
+    create("ParamsDetails", {
+      parameters: parameters,
+    }),
+    "\n\n",
+  ];
 }

package/src/markdown/createRequestSchema.ts

@@ -5,11 +5,7 @@
  * LICENSE file in the root directory of this source tree.
  * ========================================================================== */
 
-import { createDescription } from "./createDescription";
-import { createDetails } from "./createDetails";
-import { createDetailsSummary } from "./createDetailsSummary";
-import { createNodes } from "./createSchema";
-import { create, guard } from "./utils";
+import { create } from "./utils";
 import { MediaTypeObject } from "../openapi/types";
 
 interface Props {
@@ -25,142 +21,12 @@ interface Props {
 }
 
 export function createRequestSchema({ title, body, ...rest }: Props) {
-  if (
-    body === undefined ||
-    body.content === undefined ||
-    Object.keys(body).length === 0 ||
-    Object.keys(body.content).length === 0
-  ) {
-    return undefined;
-  }
-
-  // Get all MIME types, including vendor-specific
-  const mimeTypes = Object.keys(body.content);
-
-  if (mimeTypes && mimeTypes.length > 1) {
-    return create("MimeTabs", {
-      className: "openapi-tabs__mime",
-      schemaType: "request",
-      children: mimeTypes.map((mimeType) => {
-        const firstBody = body.content![mimeType].schema;
-        if (firstBody === undefined) {
-          return undefined;
-        }
-        if (firstBody.properties !== undefined) {
-          if (Object.keys(firstBody.properties).length === 0) {
-            return undefined;
-          }
-        }
-        return create("TabItem", {
-          label: mimeType,
-          value: `${mimeType}`,
-          children: [
-            createDetails({
-              className: "openapi-markdown__details mime",
-              "data-collapsed": false,
-              open: true,
-              ...rest,
-              children: [
-                createDetailsSummary({
-                  className: "openapi-markdown__details-summary-mime",
-                  children: [
-                    create("h3", {
-                      className:
-                        "openapi-markdown__details-summary-header-body",
-                      children: `${title}`,
-                    }),
-                    guard(body.required && body.required === true, () => [
-                      create("span", {
-                        className: "openapi-schema__required",
-                        children: "required",
-                      }),
-                    ]),
-                  ],
-                }),
-                create("div", {
-                  style: { textAlign: "left", marginLeft: "1rem" },
-                  children: [
-                    guard(body.description, () => [
-                      create("div", {
-                        style: { marginTop: "1rem", marginBottom: "1rem" },
-                        children: createDescription(body.description),
-                      }),
-                    ]),
-                  ],
-                }),
-                create("ul", {
-                  style: { marginLeft: "1rem" },
-                  children: createNodes(firstBody, "request"),
-                }),
-              ],
-            }),
-          ],
-        });
-      }),
-    });
-  }
-
-  const randomFirstKey = Object.keys(body.content)[0];
-  const firstBody: any =
-    body.content[randomFirstKey].schema ?? body.content![randomFirstKey];
-
-  if (firstBody === undefined) {
-    return undefined;
-  }
-
-  return create("MimeTabs", {
-    className: "openapi-tabs__mime",
-    children: [
-      create("TabItem", {
-        label: randomFirstKey,
-        value: `${randomFirstKey}-schema`,
-        children: [
-          createDetails({
-            className: "openapi-markdown__details mime",
-            "data-collapsed": false,
-            open: true,
-            ...rest,
-            children: [
-              createDetailsSummary({
-                className: "openapi-markdown__details-summary-mime",
-                children: [
-                  create("h3", {
-                    className: "openapi-markdown__details-summary-header-body",
-                    children: `${title}`,
-                  }),
-                  guard(firstBody.type === "array", (format) =>
-                    create("span", {
-                      style: { opacity: "0.6" },
-                      children: ` array`,
-                    })
-                  ),
-                  guard(body.required, () => [
-                    create("strong", {
-                      className: "openapi-schema__required",
-                      children: "required",
-                    }),
-                  ]),
-                ],
-              }),
-              create("div", {
-                style: { textAlign: "left", marginLeft: "1rem" },
-                children: [
-                  guard(body.description, () => [
-                    create("div", {
-                      style: { marginTop: "1rem", marginBottom: "1rem" },
-                      children: createDescription(body.description),
-                    }),
-                  ]),
-                ],
-              }),
-              create("ul", {
-                style: { marginLeft: "1rem" },
-                children: createNodes(firstBody, "request"),
-              }),
-            ],
-          }),
-        ],
-      }),
-    ],
-  });
+  return [
+    create("RequestSchema", {
+      title: title,
+      body: body,
+      ...rest,
+    }),
+    "\n\n",
+  ];
 }

package/src/markdown/createResponseSchema.ts

@@ -5,16 +5,7 @@
  * LICENSE file in the root directory of this source tree.
  * ========================================================================== */
 
-import { createDescription } from "./createDescription";
-import { createDetails } from "./createDetails";
-import { createDetailsSummary } from "./createDetailsSummary";
-import { createNodes } from "./createSchema";
-import {
-  createExampleFromSchema,
-  createResponseExample,
-  createResponseExamples,
-} from "./createStatusCodes";
-import { create, guard } from "./utils";
+import { create } from "./utils";
 import { MediaTypeObject } from "../openapi/types";
 
 interface Props {
@@ -30,106 +21,12 @@ interface Props {
 }
 
 export function createResponseSchema({ title, body, ...rest }: Props) {
-  if (
-    body === undefined ||
-    body.content === undefined ||
-    Object.keys(body).length === 0 ||
-    Object.keys(body.content).length === 0
-  ) {
-    return undefined;
-  }
-
-  // Get all MIME types, including vendor-specific
-  const mimeTypes = Object.keys(body.content);
-
-  if (mimeTypes && mimeTypes.length) {
-    return create("MimeTabs", {
-      className: "openapi-tabs__mime",
-      schemaType: "response",
-      children: mimeTypes.map((mimeType: any) => {
-        const responseExamples = body.content![mimeType].examples;
-        const responseExample = body.content![mimeType].example;
-        const firstBody: any =
-          body.content![mimeType].schema ?? body.content![mimeType];
-
-        if (
-          firstBody === undefined &&
-          responseExample === undefined &&
-          responseExamples === undefined
-        ) {
-          return undefined;
-        }
-
-        return create("TabItem", {
-          label: `${mimeType}`,
-          value: `${mimeType}`,
-          children: [
-            create("SchemaTabs", {
-              className: "openapi-tabs__schema",
-              // TODO: determine if we should persist this
-              // groupId: "schema-tabs",
-              children: [
-                firstBody &&
-                  create("TabItem", {
-                    label: `${title}`,
-                    value: `${title}`,
-                    children: [
-                      createDetails({
-                        className: "openapi-markdown__details response",
-                        "data-collapsed": false,
-                        open: true,
-                        ...rest,
-                        children: [
-                          createDetailsSummary({
-                            className:
-                              "openapi-markdown__details-summary-response",
-                            children: [
-                              create("strong", { children: `${title}` }),
-                              guard(
-                                body.required && body.required === true,
-                                () => [
-                                  create("span", {
-                                    className: "openapi-schema__required",
-                                    children: "required",
-                                  }),
-                                ]
-                              ),
-                            ],
-                          }),
-                          create("div", {
-                            style: { textAlign: "left", marginLeft: "1rem" },
-                            children: [
-                              guard(body.description, () => [
-                                create("div", {
-                                  style: {
-                                    marginTop: "1rem",
-                                    marginBottom: "1rem",
-                                  },
-                                  children: createDescription(body.description),
-                                }),
-                              ]),
-                            ],
-                          }),
-                          create("ul", {
-                            style: { marginLeft: "1rem" },
-                            children: createNodes(firstBody!, "response"),
-                          }),
-                        ],
-                      }),
-                    ],
-                  }),
-                firstBody && createExampleFromSchema(firstBody, mimeType),
-                responseExamples &&
-                  createResponseExamples(responseExamples, mimeType),
-                responseExample &&
-                  createResponseExample(responseExample, mimeType),
-              ],
-            }),
-          ],
-        });
-      }),
-    });
-  }
-
-  return undefined;
+  return [
+    create("ResponseSchema", {
+      title: title,
+      body: body,
+      ...rest,
+    }),
+    "\n\n",
+  ];
 }