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

package/lib/index.d.ts

@@ -1,4 +1,8 @@
 import type { LoadContext, Plugin } from "@docusaurus/types";
 import type { PluginOptions, LoadedContent } from "./types";
 export declare function isURL(str: string): boolean;
-export default function pluginOpenAPI(context: LoadContext, options: PluginOptions): Plugin<LoadedContent>;
+declare function pluginOpenAPIDocs(context: LoadContext, options: PluginOptions): Plugin<LoadedContent>;
+declare namespace pluginOpenAPIDocs {
+    var validateOptions: ({ options, validate }: any) => any;
+}
+export default pluginOpenAPIDocs;

package/lib/index.js

@@ -17,12 +17,13 @@ const chalk_1 = __importDefault(require("chalk"));
 const mustache_1 = require("mustache");
 const markdown_1 = require("./markdown");
 const openapi_1 = require("./openapi");
+const options_1 = require("./options");
 const sidebars_1 = __importDefault(require("./sidebars"));
 function isURL(str) {
     return /^(https?:)\/\//m.test(str);
 }
 exports.isURL = isURL;
-function pluginOpenAPI(context, options) {
+function pluginOpenAPIDocs(context, options) {
     let { config } = options;
     let { siteDir } = context;
     async function generateApiDocs(options) {
@@ -44,8 +45,7 @@ function pluginOpenAPI(context, options) {
             }
             // TODO: figure out better way to set default
             if (Object.keys(sidebarOptions !== null && sidebarOptions !== void 0 ? sidebarOptions : {}).length > 0) {
-                const sidebarSlice = (0, sidebars_1.default)(sidebarOptions, // TODO: find a better way to handle null
-                options, loadedApi, tags);
+                const sidebarSlice = (0, sidebars_1.default)(sidebarOptions, options, loadedApi, tags);
                 const sidebarSliceTemplate = template
                     ? fs_1.default.readFileSync(template).toString()
                     : `module.exports = {{{slice}}};`;
@@ -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`,
+        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,7 +341,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];
+                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);
+                }
+            });
         },
     };
 }
-exports.default = pluginOpenAPI;
+exports.default = pluginOpenAPIDocs;
+pluginOpenAPIDocs.validateOptions = ({ options, validate }) => {
+    const validatedOptions = validate(options_1.OptionsSchema, options);
+    return validatedOptions;
+};

package/lib/markdown/createParamsDetails.js

@@ -19,6 +19,8 @@ function createParamsDetails({ parameters, type }) {
         return undefined;
     }
     return (0, createDetails_1.createDetails)({
+        "data-collapsed": false,
+        open: true,
         style: { marginBottom: "1rem" },
         children: [
             (0, createDetailsSummary_1.createDetailsSummary)({

package/lib/markdown/createSchemaDetails.js

@@ -206,6 +206,8 @@ function createSchemaDetails({ title, body, ...rest }) {
         }
     }
     return (0, createDetails_1.createDetails)({
+        "data-collapsed": false,
+        open: true,
         ...rest,
         children: [
             (0, createDetailsSummary_1.createDetailsSummary)({

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.d.ts

@@ -1,4 +1,2 @@
 import { Joi } from "@docusaurus/utils-validation";
-import type { PluginOptions } from "./types";
-export declare const DEFAULT_OPTIONS: PluginOptions;
 export declare const OptionsSchema: Joi.ObjectSchema<any>;

package/lib/options.js

@@ -6,13 +6,42 @@
  * LICENSE file in the root directory of this source tree.
  * ========================================================================== */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.OptionsSchema = exports.DEFAULT_OPTIONS = void 0;
+exports.OptionsSchema = void 0;
 const utils_validation_1 = require("@docusaurus/utils-validation");
-exports.DEFAULT_OPTIONS = {
-    id: "default",
-    config: {},
-};
+const sidebarOptions = utils_validation_1.Joi.object({
+    contentDocsPath: utils_validation_1.Joi.string(),
+    groupPathsBy: utils_validation_1.Joi.string().valid("tag"),
+    categoryLinkSource: utils_validation_1.Joi.string().valid("tag", "info"),
+    customProps: utils_validation_1.Joi.object(),
+    sidebarCollapsible: utils_validation_1.Joi.boolean(),
+    sidebarCollapsed: utils_validation_1.Joi.boolean(),
+}).with("groupPathsBy", "contentDocsPath");
 exports.OptionsSchema = utils_validation_1.Joi.object({
-    id: utils_validation_1.Joi.string().default(exports.DEFAULT_OPTIONS.id),
-    config: utils_validation_1.Joi.object().default(exports.DEFAULT_OPTIONS.config),
+    id: utils_validation_1.Joi.string().required(),
+    config: 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(),
+        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/index.js

@@ -20,7 +20,7 @@ function isInfoItem(item) {
 }
 function groupByTags(items, sidebarOptions, options, tags) {
     const { outputDir } = options;
-    const { sidebarCollapsed, sidebarCollapsible, customProps, categoryLinkSource, } = sidebarOptions;
+    const { sidebarCollapsed, sidebarCollapsible, customProps, categoryLinkSource, contentDocsPath, } = sidebarOptions;
     const apiItems = items.filter(isApiItem);
     const infoItems = items.filter(isInfoItem);
     const intros = infoItems.map((item) => {
@@ -35,10 +35,9 @@ function groupByTags(items, sidebarOptions, options, tags) {
     const apiTags = (0, uniq_1.default)(apiItems
         .flatMap((item) => item.api.tags)
         .filter((item) => !!item));
-    // TODO: optimize this or make it a function
-    const basePath = outputDir
-        .slice(outputDir.indexOf("/", 1))
-        .replace(/^\/+/g, "");
+    const basePath = contentDocsPath
+        ? outputDir.split(contentDocsPath)[1].replace(/^\/+/g, "")
+        : outputDir.slice(outputDir.indexOf("/", 1)).replace(/^\/+/g, "");
     function createDocItem(item) {
         var _a, _b;
         const sidebar_label = item.frontMatter.sidebar_label;
@@ -46,7 +45,7 @@ function groupByTags(items, sidebarOptions, options, tags) {
         const id = item.id;
         return {
             type: "doc",
-            id: `${basePath}/${item.id}`,
+            id: basePath === "" || undefined ? `${item.id}` : `${basePath}/${item.id}`,
             label: (_b = (_a = sidebar_label) !== null && _a !== void 0 ? _a : title) !== null && _b !== void 0 ? _b : id,
             customProps: customProps,
             className: (0, clsx_1.default)({

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[];
@@ -69,6 +81,7 @@ export interface ApiNavLink {
     permalink: string;
 }
 export interface SidebarOptions {
+    contentDocsPath?: string;
     groupPathsBy?: string;
     categoryLinkSource?: string;
     customProps?: {

package/package.json

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

package/src/index.ts

@@ -15,6 +15,7 @@ import { render } from "mustache";
 
 import { createApiPageMD, createInfoPageMD, createTagPageMD } from "./markdown";
 import { readOpenapiFiles, processOpenapiFiles } from "./openapi";
+import { OptionsSchema } from "./options";
 import generateSidebarSlice from "./sidebars";
 import type { PluginOptions, LoadedContent, APIOptions } from "./types";
 
@@ -22,7 +23,7 @@ export function isURL(str: string): boolean {
   return /^(https?:)\/\//m.test(str);
 }
 
-export default function pluginOpenAPI(
+export default function pluginOpenAPIDocs(
   context: LoadContext,
   options: PluginOptions
 ): Plugin<LoadedContent> {
@@ -57,7 +58,7 @@ export default function pluginOpenAPI(
       // TODO: figure out better way to set default
       if (Object.keys(sidebarOptions ?? {}).length > 0) {
         const sidebarSlice = generateSidebarSlice(
-          sidebarOptions!, // TODO: find a better way to handle null
+          sidebarOptions!,
           options,
           loadedApi,
           tags
@@ -254,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) => {
@@ -287,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`,
+    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]);
@@ -309,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]);
@@ -336,6 +451,51 @@ 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);
+          }
+        });
     },
   };
 }
+
+pluginOpenAPIDocs.validateOptions = ({ options, validate }: any) => {
+  const validatedOptions = validate(OptionsSchema, options);
+  return validatedOptions;
+};

package/src/markdown/createParamsDetails.ts

@@ -25,6 +25,8 @@ export function createParamsDetails({ parameters, type }: Props) {
   }
 
   return createDetails({
+    "data-collapsed": false,
+    open: true,
     style: { marginBottom: "1rem" },
     children: [
       createDetailsSummary({

package/src/markdown/createSchemaDetails.ts

@@ -269,6 +269,8 @@ export function createSchemaDetails({ title, body, ...rest }: Props) {
   }
 
   return createDetails({
+    "data-collapsed": false,
+    open: true,
     ...rest,
     children: [
       createDetailsSummary({

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

@@ -7,14 +7,47 @@
 
 import { Joi } from "@docusaurus/utils-validation";
 
-import type { PluginOptions } from "./types";
-
-export const DEFAULT_OPTIONS: PluginOptions = {
-  id: "default",
-  config: {},
-};
+const sidebarOptions = Joi.object({
+  contentDocsPath: Joi.string(),
+  groupPathsBy: Joi.string().valid("tag"),
+  categoryLinkSource: Joi.string().valid("tag", "info"),
+  customProps: Joi.object(),
+  sidebarCollapsible: Joi.boolean(),
+  sidebarCollapsed: Joi.boolean(),
+}).with("groupPathsBy", "contentDocsPath");
 
 export const OptionsSchema = Joi.object({
-  id: Joi.string().default(DEFAULT_OPTIONS.id),
-  config: Joi.object().default(DEFAULT_OPTIONS.config),
+  id: Joi.string().required(),
+  config: Joi.object()
+    .pattern(
+      /^/,
+      Joi.object({
+        specPath: Joi.string().required(),
+        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/index.ts

@@ -43,6 +43,7 @@ function groupByTags(
     sidebarCollapsible,
     customProps,
     categoryLinkSource,
+    contentDocsPath,
   } = sidebarOptions;
 
   const apiItems = items.filter(isApiItem);
@@ -63,10 +64,9 @@ function groupByTags(
       .filter((item): item is string => !!item)
   );
 
-  // TODO: optimize this or make it a function
-  const basePath = outputDir
-    .slice(outputDir.indexOf("/", 1))
-    .replace(/^\/+/g, "");
+  const basePath = contentDocsPath
+    ? outputDir.split(contentDocsPath!)[1].replace(/^\/+/g, "")
+    : outputDir.slice(outputDir.indexOf("/", 1)).replace(/^\/+/g, "");
 
   function createDocItem(item: ApiPageMetadata): SidebarItemDoc {
     const sidebar_label = item.frontMatter.sidebar_label;
@@ -74,7 +74,8 @@ function groupByTags(
     const id = item.id;
     return {
       type: "doc" as const,
-      id: `${basePath}/${item.id}`,
+      id:
+        basePath === "" || undefined ? `${item.id}` : `${basePath}/${item.id}`,
       label: (sidebar_label as string) ?? title ?? id,
       customProps: customProps,
       className: clsx(

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 {
@@ -101,6 +114,7 @@ export interface ApiNavLink {
 }
 
 export interface SidebarOptions {
+  contentDocsPath?: string;
   groupPathsBy?: string;
   categoryLinkSource?: string;
   customProps?: { [key: string]: unknown };