docusaurus-plugin-openapi-docs 0.0.0-375 → 0.0.0-376

package/lib/index.js

@@ -192,9 +192,11 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
         const apiDir = path_1.default.join(siteDir, outputDir);
         const apiMdxFiles = await (0, utils_1.Globby)(["*.api.mdx", "*.info.mdx", "*.tag.mdx"], {
             cwd: path_1.default.resolve(apiDir),
+            deep: 1,
         });
         const sidebarFile = await (0, utils_1.Globby)(["sidebar.js"], {
             cwd: path_1.default.resolve(apiDir),
+            deep: 1,
         });
         apiMdxFiles.map((mdx) => fs_1.default.unlink(`${apiDir}/${mdx}`, (err) => {
             if (err) {
@@ -213,18 +215,48 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
             }
         }));
     }
+    async function generateVersions(versions, outputDir) {
+        let versionsArray = [];
+        for (const [version, metadata] of Object.entries(versions)) {
+            versionsArray.push({
+                version: version,
+                label: metadata.label,
+                baseUrl: metadata.baseUrl,
+            });
+        }
+        const versionsJson = JSON.stringify(versionsArray, null, 2);
+        try {
+            fs_1.default.writeFileSync(`${outputDir}/versions.json`, versionsJson, "utf8");
+            console.log(chalk_1.default.green(`Successfully created "${outputDir}/versions.json"`));
+        }
+        catch (err) {
+            console.error(chalk_1.default.red(`Failed to write "${outputDir}/versions.json"`), chalk_1.default.yellow(err));
+        }
+    }
+    async function cleanVersions(outputDir) {
+        if (fs_1.default.existsSync(`${outputDir}/versions.json`)) {
+            fs_1.default.unlink(`${outputDir}/versions.json`, (err) => {
+                if (err) {
+                    console.error(chalk_1.default.red(`Cleanup failed for "${outputDir}/versions.json"`), chalk_1.default.yellow(err));
+                }
+                else {
+                    console.log(chalk_1.default.green(`Cleanup succeeded for "${outputDir}/versions.json"`));
+                }
+            });
+        }
+    }
     return {
         name: `docusaurus-plugin-openapi-docs`,
         extendCli(cli) {
             cli
                 .command(`gen-api-docs`)
-                .description(`Generates API Docs mdx and sidebars.`)
-                .usage("[options] <id key value in plugin config within docusaurus.config.js>")
+                .description(`Generates OpenAPI docs in MDX file format and sidebar.js (if enabled).`)
+                .usage("<id>")
                 .arguments("<id>")
                 .action(async (id) => {
                 if (id === "all") {
                     if (config[id]) {
-                        console.error(chalk_1.default.red("Can't use id 'all' for API Doc."));
+                        console.error(chalk_1.default.red("Can't use id 'all' for OpenAPI docs configuration key."));
                     }
                     else {
                         Object.keys(config).forEach(async function (key) {
@@ -233,21 +265,71 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
                     }
                 }
                 else if (!config[id]) {
-                    console.error(chalk_1.default.red(`ID ${id} does not exist in openapi-plugin config`));
+                    console.error(chalk_1.default.red(`ID '${id}' does not exist in OpenAPI docs config.`));
                 }
                 else {
                     await generateApiDocs(config[id]);
                 }
             });
+            cli
+                .command(`gen-api-docs:version`)
+                .description(`Generates versioned OpenAPI docs in MDX file format, versions.js and sidebar.js (if enabled).`)
+                .usage("<id:version>")
+                .arguments("<id:version>")
+                .action(async (id) => {
+                const [parentId, versionId] = id.split(":");
+                const parentConfig = Object.assign({}, config[parentId]);
+                const version = parentConfig.version;
+                const label = parentConfig.label;
+                const baseUrl = parentConfig.baseUrl;
+                let parentVersion = {};
+                parentVersion[version] = { label: label, baseUrl: baseUrl };
+                const { versions } = config[parentId];
+                const mergedVersions = Object.assign(parentVersion, versions);
+                // Prepare for merge
+                delete parentConfig.versions;
+                delete parentConfig.version;
+                delete parentConfig.label;
+                delete parentConfig.baseUrl;
+                // TODO: handle when no versions are defined by version command is passed
+                if (versionId === "all") {
+                    if (versions[id]) {
+                        console.error(chalk_1.default.red("Can't use id 'all' for OpenAPI docs versions configuration key."));
+                    }
+                    else {
+                        await generateVersions(mergedVersions, parentConfig.outputDir);
+                        Object.keys(versions).forEach(async (key) => {
+                            const versionConfig = versions[key];
+                            const mergedConfig = {
+                                ...parentConfig,
+                                ...versionConfig,
+                            };
+                            await generateApiDocs(mergedConfig);
+                        });
+                    }
+                }
+                else if (!versions[versionId]) {
+                    console.error(chalk_1.default.red(`Version ID '${versionId}' does not exist in OpenAPI docs versions config.`));
+                }
+                else {
+                    const versionConfig = versions[versionId];
+                    const mergedConfig = {
+                        ...parentConfig,
+                        ...versionConfig,
+                    };
+                    await generateVersions(mergedVersions, parentConfig.outputDir);
+                    await generateApiDocs(mergedConfig);
+                }
+            });
             cli
                 .command(`clean-api-docs`)
-                .description(`Clears the Generated API Docs mdx and sidebars.`)
-                .usage("[options] <id key value in plugin config within docusaurus.config.js>")
+                .description(`Clears the generated OpenAPI docs MDX files and sidebar.js (if enabled).`)
+                .usage("<id>")
                 .arguments("<id>")
                 .action(async (id) => {
                 if (id === "all") {
                     if (config[id]) {
-                        console.error(chalk_1.default.red("Can't use id 'all' for API Doc."));
+                        console.error(chalk_1.default.red("Can't use id 'all' for OpenAPI docs configuration key."));
                     }
                     else {
                         Object.keys(config).forEach(async function (key) {
@@ -259,6 +341,41 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
                     await cleanApiDocs(config[id]);
                 }
             });
+            cli
+                .command(`clean-api-docs:version`)
+                .description(`Clears the versioned, generated OpenAPI docs MDX files, versions.json and sidebar.js (if enabled).`)
+                .usage("<id:version>")
+                .arguments("<id:version>")
+                .action(async (id) => {
+                const [parentId, versionId] = id.split(":");
+                const { versions } = config[parentId];
+                const parentConfig = Object.assign({}, config[parentId]);
+                delete parentConfig.versions;
+                if (versionId === "all") {
+                    if (versions[id]) {
+                        chalk_1.default.red("Can't use id 'all' for OpenAPI docs versions configuration key.");
+                    }
+                    else {
+                        await cleanVersions(parentConfig.outputDir);
+                        Object.keys(versions).forEach(async (key) => {
+                            const versionConfig = versions[key];
+                            const mergedConfig = {
+                                ...parentConfig,
+                                ...versionConfig,
+                            };
+                            await cleanApiDocs(mergedConfig);
+                        });
+                    }
+                }
+                else {
+                    const versionConfig = versions[versionId];
+                    const mergedConfig = {
+                        ...parentConfig,
+                        ...versionConfig,
+                    };
+                    await cleanApiDocs(mergedConfig);
+                }
+            });
         },
     };
 }

package/lib/markdown/index.js

@@ -40,7 +40,7 @@ exports.createApiPageMD = createApiPageMD;
 function createInfoPageMD({ info: { title, version, description, contact, license, termsOfService }, securitySchemes, }) {
     return (0, utils_1.render)([
         `import Tabs from "@theme/Tabs";\n`,
-        `import TabItem from "@theme/TabItem";\n`,
+        `import TabItem from "@theme/TabItem";\n\n`,
         (0, createVersionBadge_1.createVersionBadge)(version),
         `# ${(0, lodash_1.escape)(title)}\n\n`,
         (0, createDescription_1.createDescription)(description),

package/lib/options.js

@@ -24,6 +24,24 @@ exports.OptionsSchema = utils_validation_1.Joi.object({
         outputDir: utils_validation_1.Joi.string().required(),
         template: utils_validation_1.Joi.string(),
         sidebarOptions: sidebarOptions,
+        version: utils_validation_1.Joi.string().when("versions", {
+            is: utils_validation_1.Joi.exist(),
+            then: utils_validation_1.Joi.required(),
+        }),
+        label: utils_validation_1.Joi.string().when("versions", {
+            is: utils_validation_1.Joi.exist(),
+            then: utils_validation_1.Joi.required(),
+        }),
+        baseUrl: utils_validation_1.Joi.string().when("versions", {
+            is: utils_validation_1.Joi.exist(),
+            then: utils_validation_1.Joi.required(),
+        }),
+        versions: utils_validation_1.Joi.object().pattern(/^/, utils_validation_1.Joi.object({
+            specPath: utils_validation_1.Joi.string().required(),
+            outputDir: utils_validation_1.Joi.string().required(),
+            label: utils_validation_1.Joi.string().required(),
+            baseUrl: utils_validation_1.Joi.string().required(),
+        })),
     }))
         .required(),
 });

package/lib/sidebars/utils.d.ts

@@ -0,0 +1,2 @@
+export declare function versionSelector(versions: object[]): string;
+export declare function versionCrumb(version: string): string;

package/lib/sidebars/utils.js

@@ -0,0 +1,31 @@
+"use strict";
+/* ============================================================================
+ * Copyright (c) Palo Alto Networks
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ * ========================================================================== */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.versionCrumb = exports.versionSelector = void 0;
+const mustache_1 = require("mustache");
+function versionSelector(versions) {
+    const template = `<div class="dropdown dropdown--hoverable dropdown--right">
+  <button class="button button--block button--sm button--secondary"><span>Select API Version</span></button>
+  <ul class="dropdown__menu">
+    {{#.}}<li><a class="dropdown__link" href="{{{baseUrl}}}">{{{label}}}</a></li>{{/.}}
+  </ul>
+</div>
+      `;
+    const view = (0, mustache_1.render)(template, versions);
+    return view;
+}
+exports.versionSelector = versionSelector;
+function versionCrumb(version) {
+    const template = `<ul style="display: flex;" class="breadcrumbs breadcrumbs--sm">
+  <li style="margin-left: auto; margin-right: 0;" class="breadcrumbs__item breadcrumbs__item--active">
+  <a class="breadcrumbs__link"><span>{{{.}}}</span></a></li></ul>
+      `;
+    const view = (0, mustache_1.render)(template, version);
+    return view;
+}
+exports.versionCrumb = versionCrumb;

package/lib/types.d.ts

@@ -12,6 +12,18 @@ export interface APIOptions {
     outputDir: string;
     template?: string;
     sidebarOptions?: SidebarOptions;
+    version?: string;
+    label?: string;
+    baseUrl?: string;
+    versions?: {
+        [key: string]: APIVersionOptions;
+    };
+}
+export interface APIVersionOptions {
+    specPath: string;
+    outputDir: string;
+    label: string;
+    baseUrl: string;
 }
 export interface LoadedContent {
     loadedApi: ApiMetadata[];

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "docusaurus-plugin-openapi-docs",
   "description": "OpenAPI plugin for Docusaurus.",
-  "version": "0.0.0-375",
+  "version": "0.0.0-376",
   "license": "MIT",
   "keywords": [
     "openapi",
@@ -62,5 +62,5 @@
   "engines": {
     "node": ">=14"
   },
-  "gitHead": "cfb3b0d1f222d9e545bbb66d1a40f6648cb37f8b"
+  "gitHead": "1a772d94e5e7075dff6f522aef9aab9303a0e007"
 }

package/src/index.ts

@@ -255,9 +255,11 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
     const apiDir = path.join(siteDir, outputDir);
     const apiMdxFiles = await Globby(["*.api.mdx", "*.info.mdx", "*.tag.mdx"], {
       cwd: path.resolve(apiDir),
+      deep: 1,
     });
     const sidebarFile = await Globby(["sidebar.js"], {
       cwd: path.resolve(apiDir),
+      deep: 1,
     });
     apiMdxFiles.map((mdx) =>
       fs.unlink(`${apiDir}/${mdx}`, (err) => {
@@ -288,21 +290,66 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
     );
   }
 
+  async function generateVersions(versions: object, outputDir: string) {
+    let versionsArray = [] as object[];
+    for (const [version, metadata] of Object.entries(versions)) {
+      versionsArray.push({
+        version: version,
+        label: metadata.label,
+        baseUrl: metadata.baseUrl,
+      });
+    }
+
+    const versionsJson = JSON.stringify(versionsArray, null, 2);
+    try {
+      fs.writeFileSync(`${outputDir}/versions.json`, versionsJson, "utf8");
+      console.log(
+        chalk.green(`Successfully created "${outputDir}/versions.json"`)
+      );
+    } catch (err) {
+      console.error(
+        chalk.red(`Failed to write "${outputDir}/versions.json"`),
+        chalk.yellow(err)
+      );
+    }
+  }
+
+  async function cleanVersions(outputDir: string) {
+    if (fs.existsSync(`${outputDir}/versions.json`)) {
+      fs.unlink(`${outputDir}/versions.json`, (err) => {
+        if (err) {
+          console.error(
+            chalk.red(`Cleanup failed for "${outputDir}/versions.json"`),
+            chalk.yellow(err)
+          );
+        } else {
+          console.log(
+            chalk.green(`Cleanup succeeded for "${outputDir}/versions.json"`)
+          );
+        }
+      });
+    }
+  }
+
   return {
     name: `docusaurus-plugin-openapi-docs`,
 
     extendCli(cli): void {
       cli
         .command(`gen-api-docs`)
-        .description(`Generates API Docs mdx and sidebars.`)
-        .usage(
-          "[options] <id key value in plugin config within docusaurus.config.js>"
+        .description(
+          `Generates OpenAPI docs in MDX file format and sidebar.js (if enabled).`
         )
+        .usage("<id>")
         .arguments("<id>")
         .action(async (id) => {
           if (id === "all") {
             if (config[id]) {
-              console.error(chalk.red("Can't use id 'all' for API Doc."));
+              console.error(
+                chalk.red(
+                  "Can't use id 'all' for OpenAPI docs configuration key."
+                )
+              );
             } else {
               Object.keys(config).forEach(async function (key) {
                 await generateApiDocs(config[key]);
@@ -310,24 +357,91 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
             }
           } else if (!config[id]) {
             console.error(
-              chalk.red(`ID ${id} does not exist in openapi-plugin config`)
+              chalk.red(`ID '${id}' does not exist in OpenAPI docs config.`)
             );
           } else {
             await generateApiDocs(config[id]);
           }
         });
 
+      cli
+        .command(`gen-api-docs:version`)
+        .description(
+          `Generates versioned OpenAPI docs in MDX file format, versions.js and sidebar.js (if enabled).`
+        )
+        .usage("<id:version>")
+        .arguments("<id:version>")
+        .action(async (id) => {
+          const [parentId, versionId] = id.split(":");
+          const parentConfig = Object.assign({}, config[parentId]);
+
+          const version = parentConfig.version as string;
+          const label = parentConfig.label as string;
+          const baseUrl = parentConfig.baseUrl as string;
+
+          let parentVersion = {} as any;
+          parentVersion[version] = { label: label, baseUrl: baseUrl };
+
+          const { versions } = config[parentId] as any;
+          const mergedVersions = Object.assign(parentVersion, versions);
+
+          // Prepare for merge
+          delete parentConfig.versions;
+          delete parentConfig.version;
+          delete parentConfig.label;
+          delete parentConfig.baseUrl;
+
+          // TODO: handle when no versions are defined by version command is passed
+          if (versionId === "all") {
+            if (versions[id]) {
+              console.error(
+                chalk.red(
+                  "Can't use id 'all' for OpenAPI docs versions configuration key."
+                )
+              );
+            } else {
+              await generateVersions(mergedVersions, parentConfig.outputDir);
+              Object.keys(versions).forEach(async (key) => {
+                const versionConfig = versions[key];
+                const mergedConfig = {
+                  ...parentConfig,
+                  ...versionConfig,
+                };
+                await generateApiDocs(mergedConfig);
+              });
+            }
+          } else if (!versions[versionId]) {
+            console.error(
+              chalk.red(
+                `Version ID '${versionId}' does not exist in OpenAPI docs versions config.`
+              )
+            );
+          } else {
+            const versionConfig = versions[versionId];
+            const mergedConfig = {
+              ...parentConfig,
+              ...versionConfig,
+            };
+            await generateVersions(mergedVersions, parentConfig.outputDir);
+            await generateApiDocs(mergedConfig);
+          }
+        });
+
       cli
         .command(`clean-api-docs`)
-        .description(`Clears the Generated API Docs mdx and sidebars.`)
-        .usage(
-          "[options] <id key value in plugin config within docusaurus.config.js>"
+        .description(
+          `Clears the generated OpenAPI docs MDX files and sidebar.js (if enabled).`
         )
+        .usage("<id>")
         .arguments("<id>")
         .action(async (id) => {
           if (id === "all") {
             if (config[id]) {
-              console.error(chalk.red("Can't use id 'all' for API Doc."));
+              console.error(
+                chalk.red(
+                  "Can't use id 'all' for OpenAPI docs configuration key."
+                )
+              );
             } else {
               Object.keys(config).forEach(async function (key) {
                 await cleanApiDocs(config[key]);
@@ -337,6 +451,46 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
             await cleanApiDocs(config[id]);
           }
         });
+
+      cli
+        .command(`clean-api-docs:version`)
+        .description(
+          `Clears the versioned, generated OpenAPI docs MDX files, versions.json and sidebar.js (if enabled).`
+        )
+        .usage("<id:version>")
+        .arguments("<id:version>")
+        .action(async (id) => {
+          const [parentId, versionId] = id.split(":");
+          const { versions } = config[parentId] as any;
+
+          const parentConfig = Object.assign({}, config[parentId]);
+          delete parentConfig.versions;
+
+          if (versionId === "all") {
+            if (versions[id]) {
+              chalk.red(
+                "Can't use id 'all' for OpenAPI docs versions configuration key."
+              );
+            } else {
+              await cleanVersions(parentConfig.outputDir);
+              Object.keys(versions).forEach(async (key) => {
+                const versionConfig = versions[key];
+                const mergedConfig = {
+                  ...parentConfig,
+                  ...versionConfig,
+                };
+                await cleanApiDocs(mergedConfig);
+              });
+            }
+          } else {
+            const versionConfig = versions[versionId];
+            const mergedConfig = {
+              ...parentConfig,
+              ...versionConfig,
+            };
+            await cleanApiDocs(mergedConfig);
+          }
+        });
     },
   };
 }

package/src/markdown/index.ts

@@ -59,7 +59,7 @@ export function createInfoPageMD({
 }: InfoPageMetadata) {
   return render([
     `import Tabs from "@theme/Tabs";\n`,
-    `import TabItem from "@theme/TabItem";\n`,
+    `import TabItem from "@theme/TabItem";\n\n`,
     createVersionBadge(version),
     `# ${escape(title)}\n\n`,
     createDescription(description),

package/src/options.ts

@@ -26,6 +26,27 @@ export const OptionsSchema = Joi.object({
         outputDir: Joi.string().required(),
         template: Joi.string(),
         sidebarOptions: sidebarOptions,
+        version: Joi.string().when("versions", {
+          is: Joi.exist(),
+          then: Joi.required(),
+        }),
+        label: Joi.string().when("versions", {
+          is: Joi.exist(),
+          then: Joi.required(),
+        }),
+        baseUrl: Joi.string().when("versions", {
+          is: Joi.exist(),
+          then: Joi.required(),
+        }),
+        versions: Joi.object().pattern(
+          /^/,
+          Joi.object({
+            specPath: Joi.string().required(),
+            outputDir: Joi.string().required(),
+            label: Joi.string().required(),
+            baseUrl: Joi.string().required(),
+          })
+        ),
       })
     )
     .required(),

package/src/sidebars/utils.ts

@@ -0,0 +1,29 @@
+/* ============================================================================
+ * Copyright (c) Palo Alto Networks
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ * ========================================================================== */
+
+import { render } from "mustache";
+
+export function versionSelector(versions: object[]) {
+  const template = `<div class="dropdown dropdown--hoverable dropdown--right">
+  <button class="button button--block button--sm button--secondary"><span>Select API Version</span></button>
+  <ul class="dropdown__menu">
+    {{#.}}<li><a class="dropdown__link" href="{{{baseUrl}}}">{{{label}}}</a></li>{{/.}}
+  </ul>
+</div>
+      `;
+  const view = render(template, versions);
+  return view;
+}
+
+export function versionCrumb(version: string) {
+  const template = `<ul style="display: flex;" class="breadcrumbs breadcrumbs--sm">
+  <li style="margin-left: auto; margin-right: 0;" class="breadcrumbs__item breadcrumbs__item--active">
+  <a class="breadcrumbs__link"><span>{{{.}}}</span></a></li></ul>
+      `;
+  const view = render(template, version);
+  return view;
+}

package/src/types.ts

@@ -32,6 +32,19 @@ export interface APIOptions {
   outputDir: string;
   template?: string;
   sidebarOptions?: SidebarOptions;
+  version?: string;
+  label?: string;
+  baseUrl?: string;
+  versions?: {
+    [key: string]: APIVersionOptions;
+  };
+}
+
+export interface APIVersionOptions {
+  specPath: string;
+  outputDir: string;
+  label: string;
+  baseUrl: string;
 }
 
 export interface LoadedContent {