docusaurus-plugin-openapi-docs 1.0.3 → 1.0.4

package/README.md

@@ -20,6 +20,13 @@ OpenAPI plugin for generating API reference docs in Docusaurus v2.
 
 The `docusaurus-plugin-openapi-docs` package extends the Docusaurus CLI with commands for generating MDX using the OpenAPI specification as the source. The resulting MDX is fully compatible with [plugin-content-docs](https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-content-docs) and can be used to render beautiful reference API docs by setting `docItemComponent` to `@theme/ApiItem`, a custom component included in the `docusaurus-theme-openapi-docs` theme.
 
+Key Features:
+
+- **Compatible:** Works with Swagger 2.0 and OpenAPI 3.x.
+- **Fast:** Convert large OpenAPI specs into MDX docs in seconds. 🔥
+- **Stylish:** Based on the same [Infima styling framework](https://infima.dev/) that powers the Docusaurus UI.
+- **Capable:** Supports single, multi and _even micro_ OpenAPI specs.
+
 ## Installation
 
 Plugin:
@@ -71,7 +78,6 @@ Here is an example of properly configuring your `docusaurus.config.js` file for
 ],
 
   plugins: [
-    [
       'docusaurus-plugin-openapi-docs',
       {
         id: "apiDocs",
@@ -97,28 +103,53 @@ Here is an example of properly configuring your `docusaurus.config.js` file for
 
 > Note: You may optionally configure a dedicated `@docusaurus/plugin-content-docs` instance for use with `docusaurus-theme-openapi-docs` by setting `docItemComponent` to `@theme/ApiItem`.
 
-### Plugin Configuration Options
+## Plugin Configuration Options
+
+The `docusaurus-plugin-openapi-docs` plugin can be configured with the following options:
+
+| Name          | Type     | Default | Description                                                                                                                                          |
+| ------------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `id`          | `string` | `null`  | A unique document id.                                                                                                                                |
+| `docPluginId` | `string` | `null`  | The ID associated with the `plugin-content-docs` or `preset` instance used to render the OpenAPI docs (e.g. "your-plugin-id", "classic", "default"). |
+
+### config
 
-`docusaurus-plugin-openapi-docs` can be configured with the following options:
+`config` can be configured with the following options:
 
-| Name             | Type     | Default | Description                                                                                                          |
-| ---------------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------- |
-| `specPath`       | `string` | `null`  | Designated path to the source of an OpenAPI specification file or directory of multiple OpenAPI specification files. |
-| `ouputDir`       | `string` | `null`  | Desired output path for generated MDX files.                                                                         |
-| `template`       | `string` | `null`  | _Optional:_ Customize MDX content with a desired template.                                                           |
-| `sidebarOptions` | `object` | `null`  | _Optional:_ Set of options for sidebar configuration. See below for a list of supported options.                     |
+| Name             | Type     | Default | Description                                                                                                                 |
+| ---------------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------- |
+| `specPath`       | `string` | `null`  | Designated URL or path to the source of an OpenAPI specification file or directory of multiple OpenAPI specification files. |
+| `ouputDir`       | `string` | `null`  | Desired output path for generated MDX files.                                                                                |
+| `ouputDir`       | `string` | `null`  | Desired output path for generated MDX files.                                                                                |
+| `template`       | `string` | `null`  | _Optional:_ Customize MDX content with a desired template.                                                                  |
+| `sidebarOptions` | `object` | `null`  | _Optional:_ Set of options for sidebar configuration. See below for a list of supported options.                            |
+| `version`        | `string` | `null`  | _Optional:_ Version assigned to single or micro-spec API specified in `specPath`.                                           |
+| `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.                         |
 
 `sidebarOptions` can be configured with the following options:
 
 | Name                 | Type      | Default | Description                                                                                                                                                                                                                                                                                                                                                                                                                                          |
 | -------------------- | --------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `groupPathsBy`       | `string`  | `null`  | Organize and group sidebar slice by specified option. Note: Currently, `groupPathsBy` only contains support for grouping by `tag`.                                                                                                                                                                                                                                                                                                                   |
-| `categoryLinkSource` | `string`  | `null`  | Defines what source to use for rendering category link pages when grouping paths by tag. <br/></br>The supported options are as follows: <br/></br> `tag`: Sets the category link config type to `generated-index` and uses the tag description as the link config description. <br/><br/>`info`: Sets the category link config type to `doc` and renders the `info` section as the category link (recommended only for multi/micro-spec scenarios). |
+| `categoryLinkSource` | `string`  | `null`  | Defines what source to use for rendering category link pages when grouping paths by tag. <br/><br/>The supported options are as follows: <br/><br/> `tag`: Sets the category link config type to `generated-index` and uses the tag description as the link config description. <br/><br/>`info`: Sets the category link config type to `doc` and renders the `info` section as the category link (recommended only for multi/micro-spec scenarios). |
 | `sidebarCollapsible` | `boolean` | `true`  | Whether sidebar categories are collapsible by default.                                                                                                                                                                                                                                                                                                                                                                                               |
 | `sidebarCollapsed`   | `boolean` | `true`  | Whether sidebar categories are collapsed by default.                                                                                                                                                                                                                                                                                                                                                                                                 |
 | `customProps`        | `object`  | `null`  | Additional props for customizing a sidebar item.                                                                                                                                                                                                                                                                                                                                                                                                     |
 
-> Note: You may optionally configure a `sidebarOptions`. In doing so, an individual `sidebar.js` slice with the configured options will be generated within the respective `outputDir`.
+> You may optionally configure a `sidebarOptions`. In doing so, an individual `sidebar.js` slice with the configured options will be generated within the respective `outputDir`.
+
+`versions` can be configured with the following options:
+
+| Name       | Type     | Default | Description                                                                                                              |
+| ---------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `specPath` | `string` | `null`  | Designated URL or path to the source of an OpenAPI specification file or directory of micro OpenAPI specification files. |
+| `ouputDir` | `string` | `null`  | Desired output path for versioned, generated MDX files.                                                                  |
+| `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.                                        |
+
+> All versions will automatically inherit `sidebarOptions` from the parent/base config.
 
 ## CLI Usage
 
@@ -139,9 +170,11 @@ Commands:
   write-translations [options] [siteDir]                   Extract required translations of your site.
   write-heading-ids [options] [siteDir] [files...]         Generate heading ids in Markdown content.
   docs:version <version>                                   Tag a new docs version
-  gen-api-docs <id>                                        Generates API Docs mdx and sidebars.
-  clean-api-docs <id>                                      Clears the Generated API Docs mdx and sidebars.
-  docs:version:openapi <version>                           Tag a new docs version (openapi)
+  gen-api-docs <id>                                        Generates OpenAPI docs in MDX file format and sidebar.js (if enabled).
+  gen-api-docs:version <id:version>                        Generates versioned OpenAPI docs in MDX file format, versions.js and sidebar.js (if enabled).
+  clean-api-docs <id>                                      Clears the generated OpenAPI docs MDX files and sidebar.js (if enabled).
+  clean-api-docs:version <id:version>                      Clears the versioned, generated OpenAPI docs MDX files, versions.json and sidebar.js (if
+                                                           enabled).
 ```
 
 ### Generating OpenAPI Docs
@@ -190,6 +223,61 @@ yarn docusaurus clean-api-docs burgers
 
 > The example above will remove all API docs relative to `burgers`.
 
+### Versioning OpenAPI docs
+
+To generate _all_ versioned OpenAPI docs, run the following command from the root directory of your project:
+
+```bash
+yarn docusaurus gen-api-docs:version <id>:all
+```
+
+Example:
+
+```bash
+yarn docusaurus gen-api-docs:version petstore:all
+```
+
+> This will generate API docs for all of the OpenAPI specification (OAS) files referenced in your `versions` config and will also generate a `versions.json` file.
+
+> Substitue `all` with a specific version ID to generate/clean a specific version. Generating for `all` or a specific version ID will automatically update the `versions.json` file.
+
+## Installing from Template
+
+Run the following to bootstrap a Docsaurus v2 site (classic theme) with `docusaurus-openapi-docs`:
+
+```bash
+npx create-docusaurus@2.0.0-beta.21 my-website --package-manager yarn
+```
+
+> When prompted to select a template choose `Git repository`.
+
+Template Repository URL:
+
+```bash
+https://github.com/PaloAltoNetworks/docusaurus-template-openapi-docs.git
+```
+
+> When asked how the template repo should be cloned choose "copy" (unless you know better).
+
+```bash
+cd my-website
+yarn
+```
+
+## Developer Quick Start
+
+> Looking to make a contribution? Make sure to checkout out our contributing guide.
+
+After [forking](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/fork) the main repository, run the following:
+
+```bash
+git clone https://github.com/<your account>/docusaurus-openapi-docs.git
+cd docusaurus-openapi-docs
+yarn
+yarn build-packages
+yarn watch:demo
+```
+
 ## Support
 
-Please read [SUPPORT.md](SUPPORT.md) for details on how to get support for this project.
+Please read [SUPPORT.md](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/blob/main/SUPPORT.md) for details on how to get support for this project.

package/lib/index.d.ts

@@ -1,4 +1,9 @@
 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>;
+export declare function getDocsData(dataArray: any[], filter: string): Object | undefined;
+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

@@ -9,7 +9,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.isURL = void 0;
+exports.getDocsData = exports.isURL = void 0;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const utils_1 = require("@docusaurus/utils");
@@ -17,14 +17,52 @@ 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) {
-    let { config } = options;
-    let { siteDir } = context;
+function getDocsData(dataArray, filter) {
+    // eslint-disable-next-line array-callback-return
+    const filteredData = dataArray.filter((data) => {
+        if (data[0] === filter) {
+            return data[1];
+        }
+        // Search plugin-content-docs instances
+        if (data[0] === "@docusaurus/plugin-content-docs") {
+            const pluginId = data[1].id ? data[1].id : "default";
+            if (pluginId === filter) {
+                return data[1];
+            }
+        }
+    })[0];
+    if (filteredData) {
+        // Search presets, e.g. "classic"
+        if (filteredData[0] === filter) {
+            return filteredData[1].docs;
+        }
+        // Search plugin-content-docs instances
+        if (filteredData[0] === "@docusaurus/plugin-content-docs") {
+            const pluginId = filteredData[1].id ? filteredData[1].id : "default";
+            if (pluginId === filter) {
+                return filteredData[1];
+            }
+        }
+    }
+    return;
+}
+exports.getDocsData = getDocsData;
+function pluginOpenAPIDocs(context, options) {
+    const { config, docPluginId } = options;
+    const { siteDir, siteConfig } = context;
+    // Get routeBasePath and path from plugin-content-docs or preset
+    const presets = siteConfig.presets;
+    const plugins = siteConfig.plugins;
+    const presetsPlugins = presets.concat(plugins);
+    const docData = getDocsData(presetsPlugins, docPluginId);
+    const docRouteBasePath = docData ? docData.routeBasePath : undefined;
+    const docPath = docData ? (docData.path ? docData.path : "docs") : undefined;
     async function generateApiDocs(options) {
         let { specPath, outputDir, template, sidebarOptions } = options;
         const contentPath = isURL(specPath)
@@ -44,8 +82,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, docPath);
                 const sidebarSliceTemplate = template
                     ? fs_1.default.readFileSync(template).toString()
                     : `module.exports = {{{slice}}};`;
@@ -135,8 +172,14 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
                 item.markdown = markdown;
                 if (item.type === "api") {
                     item.json = JSON.stringify(item.api);
+                    let infoBasePath = `${outputDir}/${item.infoId}`;
+                    if (docRouteBasePath) {
+                        infoBasePath = `${docRouteBasePath}/${outputDir
+                            .split(docPath)[1]
+                            .replace(/^\/+/g, "")}/${item.infoId}`.replace(/^\/+/g, "");
+                    }
                     if (item.infoId)
-                        item.infoPath = `${outputDir}/${item.infoId}`;
+                        item.infoPath = infoBasePath;
                 }
                 const view = (0, mustache_1.render)(mdTemplate, item);
                 const utils = (0, mustache_1.render)(infoMdTemplate, item);
@@ -192,9 +235,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 +258,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 +308,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 +384,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({
+    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(),
+});
 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(),
+    docPluginId: 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.d.ts

@@ -1,4 +1,4 @@
 import { ProcessedSidebar } from "@docusaurus/plugin-content-docs/src/sidebars/types";
 import { TagObject } from "../openapi/types";
 import type { SidebarOptions, APIOptions, ApiMetadata } from "../types";
-export default function generateSidebarSlice(sidebarOptions: SidebarOptions, options: APIOptions, api: ApiMetadata[], tags: TagObject[]): ProcessedSidebar;
+export default function generateSidebarSlice(sidebarOptions: SidebarOptions, options: APIOptions, api: ApiMetadata[], tags: TagObject[], docPath: string): ProcessedSidebar;

package/lib/sidebars/index.js

@@ -18,7 +18,7 @@ function isApiItem(item) {
 function isInfoItem(item) {
     return item.type === "info";
 }
-function groupByTags(items, sidebarOptions, options, tags) {
+function groupByTags(items, sidebarOptions, options, tags, docPath) {
     const { outputDir } = options;
     const { sidebarCollapsed, sidebarCollapsible, customProps, categoryLinkSource, } = sidebarOptions;
     const apiItems = items.filter(isApiItem);
@@ -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 = docPath
+        ? outputDir.split(docPath)[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)({
@@ -136,10 +135,10 @@ function groupByTags(items, sidebarOptions, options, tags) {
     }
     return [...tagged, ...untagged];
 }
-function generateSidebarSlice(sidebarOptions, options, api, tags) {
+function generateSidebarSlice(sidebarOptions, options, api, tags, docPath) {
     let sidebarSlice = [];
     if (sidebarOptions.groupPathsBy === "tag") {
-        sidebarSlice = groupByTags(api, sidebarOptions, options, tags);
+        sidebarSlice = groupByTags(api, sidebarOptions, options, tags, docPath);
     }
     return sidebarSlice;
 }

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

@@ -3,6 +3,7 @@ import { InfoObject, OperationObject, SecuritySchemeObject, TagObject } from "./
 export type { PropSidebarItemCategory, SidebarItemLink, PropSidebar, PropSidebarItem, } from "@docusaurus/plugin-content-docs-types";
 export interface PluginOptions {
     id?: string;
+    docPluginId: string;
     config: {
         [key: string]: APIOptions;
     };
@@ -12,6 +13,27 @@ export interface APIOptions {
     outputDir: string;
     template?: string;
     sidebarOptions?: SidebarOptions;
+    version?: string;
+    label?: string;
+    baseUrl?: string;
+    versions?: {
+        [key: string]: APIVersionOptions;
+    };
+}
+export interface SidebarOptions {
+    groupPathsBy?: string;
+    categoryLinkSource?: string;
+    customProps?: {
+        [key: string]: unknown;
+    };
+    sidebarCollapsible?: boolean;
+    sidebarCollapsed?: boolean;
+}
+export interface APIVersionOptions {
+    specPath: string;
+    outputDir: string;
+    label: string;
+    baseUrl: string;
 }
 export interface LoadedContent {
     loadedApi: ApiMetadata[];
@@ -68,12 +90,3 @@ export interface ApiNavLink {
     title: string;
     permalink: string;
 }
-export interface SidebarOptions {
-    groupPathsBy?: string;
-    categoryLinkSource?: string;
-    customProps?: {
-        [key: string]: unknown;
-    };
-    sidebarCollapsible?: boolean;
-    sidebarCollapsed?: boolean;
-}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "docusaurus-plugin-openapi-docs",
   "description": "OpenAPI plugin for Docusaurus.",
-  "version": "1.0.3",
+  "version": "1.0.4",
   "license": "MIT",
   "keywords": [
     "openapi",
@@ -62,5 +62,5 @@
   "engines": {
     "node": ">=14"
   },
-  "gitHead": "618a438ec42148f525fb92cb11d291ce50d2ad06"
+  "gitHead": "0a590e8aaaff087d13adb7b4be75aa0112b9a2b5"
 }

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,12 +23,55 @@ export function isURL(str: string): boolean {
   return /^(https?:)\/\//m.test(str);
 }
 
-export default function pluginOpenAPI(
+export function getDocsData(
+  dataArray: any[],
+  filter: string
+): Object | undefined {
+  // eslint-disable-next-line array-callback-return
+  const filteredData = dataArray.filter((data) => {
+    if (data[0] === filter) {
+      return data[1];
+    }
+
+    // Search plugin-content-docs instances
+    if (data[0] === "@docusaurus/plugin-content-docs") {
+      const pluginId = data[1].id ? data[1].id : "default";
+      if (pluginId === filter) {
+        return data[1];
+      }
+    }
+  })[0];
+  if (filteredData) {
+    // Search presets, e.g. "classic"
+    if (filteredData[0] === filter) {
+      return filteredData[1].docs;
+    }
+
+    // Search plugin-content-docs instances
+    if (filteredData[0] === "@docusaurus/plugin-content-docs") {
+      const pluginId = filteredData[1].id ? filteredData[1].id : "default";
+      if (pluginId === filter) {
+        return filteredData[1];
+      }
+    }
+  }
+  return;
+}
+
+export default function pluginOpenAPIDocs(
   context: LoadContext,
   options: PluginOptions
 ): Plugin<LoadedContent> {
-  let { config } = options;
-  let { siteDir } = context;
+  const { config, docPluginId } = options;
+  const { siteDir, siteConfig } = context;
+
+  // Get routeBasePath and path from plugin-content-docs or preset
+  const presets: any = siteConfig.presets;
+  const plugins: any = siteConfig.plugins;
+  const presetsPlugins = presets.concat(plugins);
+  const docData: any = getDocsData(presetsPlugins, docPluginId);
+  const docRouteBasePath = docData ? docData.routeBasePath : undefined;
+  const docPath = docData ? (docData.path ? docData.path : "docs") : undefined;
 
   async function generateApiDocs(options: APIOptions) {
     let { specPath, outputDir, template, sidebarOptions } = options;
@@ -57,10 +101,11 @@ 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
+          tags,
+          docPath
         );
 
         const sidebarSliceTemplate = template
@@ -163,7 +208,13 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
         item.markdown = markdown;
         if (item.type === "api") {
           item.json = JSON.stringify(item.api);
-          if (item.infoId) item.infoPath = `${outputDir}/${item.infoId}`;
+          let infoBasePath = `${outputDir}/${item.infoId}`;
+          if (docRouteBasePath) {
+            infoBasePath = `${docRouteBasePath}/${outputDir
+              .split(docPath!)[1]
+              .replace(/^\/+/g, "")}/${item.infoId}`.replace(/^\/+/g, "");
+          }
+          if (item.infoId) item.infoPath = infoBasePath;
         }
 
         const view = render(mdTemplate, item);
@@ -254,9 +305,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 +340,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 +407,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 +501,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({
+  groupPathsBy: Joi.string().valid("tag"),
+  categoryLinkSource: Joi.string().valid("tag", "info"),
+  customProps: Joi.object(),
+  sidebarCollapsible: Joi.boolean(),
+  sidebarCollapsed: Joi.boolean(),
+});
 
 export const OptionsSchema = Joi.object({
-  id: Joi.string().default(DEFAULT_OPTIONS.id),
-  config: Joi.object().default(DEFAULT_OPTIONS.config),
+  id: Joi.string().required(),
+  docPluginId: 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

@@ -35,7 +35,8 @@ function groupByTags(
   items: ApiPageMetadata[],
   sidebarOptions: SidebarOptions,
   options: APIOptions,
-  tags: TagObject[]
+  tags: TagObject[],
+  docPath: string
 ): ProcessedSidebar {
   const { outputDir } = options;
   const {
@@ -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 = docPath
+    ? outputDir.split(docPath!)[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(
@@ -183,7 +184,8 @@ export default function generateSidebarSlice(
   sidebarOptions: SidebarOptions,
   options: APIOptions,
   api: ApiMetadata[],
-  tags: TagObject[]
+  tags: TagObject[],
+  docPath: string
 ) {
   let sidebarSlice: ProcessedSidebar = [];
   if (sidebarOptions.groupPathsBy === "tag") {
@@ -191,7 +193,8 @@ export default function generateSidebarSlice(
       api as ApiPageMetadata[],
       sidebarOptions,
       options,
-      tags
+      tags,
+      docPath
     );
   }
   return sidebarSlice;

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

@@ -22,6 +22,7 @@ export type {
 } from "@docusaurus/plugin-content-docs-types";
 export interface PluginOptions {
   id?: string;
+  docPluginId: string;
   config: {
     [key: string]: APIOptions;
   };
@@ -32,6 +33,27 @@ export interface APIOptions {
   outputDir: string;
   template?: string;
   sidebarOptions?: SidebarOptions;
+  version?: string;
+  label?: string;
+  baseUrl?: string;
+  versions?: {
+    [key: string]: APIVersionOptions;
+  };
+}
+
+export interface SidebarOptions {
+  groupPathsBy?: string;
+  categoryLinkSource?: string;
+  customProps?: { [key: string]: unknown };
+  sidebarCollapsible?: boolean;
+  sidebarCollapsed?: boolean;
+}
+
+export interface APIVersionOptions {
+  specPath: string;
+  outputDir: string;
+  label: string;
+  baseUrl: string;
 }
 
 export interface LoadedContent {
@@ -99,11 +121,3 @@ export interface ApiNavLink {
   title: string;
   permalink: string;
 }
-
-export interface SidebarOptions {
-  groupPathsBy?: string;
-  categoryLinkSource?: string;
-  customProps?: { [key: string]: unknown };
-  sidebarCollapsible?: boolean;
-  sidebarCollapsed?: boolean;
-}