docusaurus-plugin-openapi-docs 1.0.1 → 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",
@@ -80,7 +86,7 @@ Here is an example of properly configuring your `docusaurus.config.js` file for
             specPath: "examples/petstore.yaml", // Path to designated spec file
             outputDir: "api/petstore", // Output directory for generated .mdx docs
             sidebarOptions: {
-              groupPathsBy: "tags",
+              groupPathsBy: "tag",
             },
           },
           burgers: {
@@ -97,27 +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 "tags". |
-| `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.                                                                                    |
+| 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). |
+| `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
 
@@ -138,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
@@ -189,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,3 +1,9 @@
 import type { LoadContext, Plugin } from "@docusaurus/types";
 import type { PluginOptions, LoadedContent } from "./types";
-export default function pluginOpenAPI(context: LoadContext, options: PluginOptions): Plugin<LoadedContent>;
+export declare function isURL(str: string): boolean;
+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,6 +9,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.getDocsData = exports.isURL = void 0;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const utils_1 = require("@docusaurus/utils");
@@ -16,16 +17,60 @@ 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 pluginOpenAPI(context, options) {
-    let { config } = options;
-    let { siteDir } = context;
+function isURL(str) {
+    return /^(https?:)\/\//m.test(str);
+}
+exports.isURL = isURL;
+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 = path_1.default.resolve(siteDir, specPath);
+        const contentPath = isURL(specPath)
+            ? specPath
+            : path_1.default.resolve(siteDir, specPath);
         try {
             const openapiFiles = await (0, openapi_1.readOpenapiFiles)(contentPath, {});
-            const loadedApi = await (0, openapi_1.processOpenapiFiles)(openapiFiles);
+            const [loadedApi, tags] = await (0, openapi_1.processOpenapiFiles)(openapiFiles, sidebarOptions);
             if (!fs_1.default.existsSync(outputDir)) {
                 try {
                     fs_1.default.mkdirSync(outputDir, { recursive: true });
@@ -37,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);
+                const sidebarSlice = (0, sidebars_1.default)(sidebarOptions, options, loadedApi, tags, docPath);
                 const sidebarSliceTemplate = template
                     ? fs_1.default.readFileSync(template).toString()
                     : `module.exports = {{{slice}}};`;
@@ -59,7 +103,12 @@ function pluginOpenAPI(context, options) {
                 ? fs_1.default.readFileSync(template).toString()
                 : `---
 id: {{{id}}}
+{{^api}}
+sidebar_label: Introduction
+{{/api}}
+{{#api}}
 sidebar_label: {{{title}}}
+{{/api}}
 {{^api}}
 sidebar_position: 0
 {{/api}}
@@ -73,17 +122,69 @@ api: {{{json}}}
 {{#api.method}}
 sidebar_class_name: "{{{api.method}}} api-method"
 {{/api.method}}
+{{#infoPath}}
+info_path: {{{infoPath}}}
+{{/infoPath}}
 ---
 
 {{{markdown}}}
+      `;
+            const infoMdTemplate = template
+                ? fs_1.default.readFileSync(template).toString()
+                : `---
+id: {{{id}}}
+sidebar_label: {{{title}}}
+hide_title: true
+---
+
+{{{markdown}}}
+
+\`\`\`mdx-code-block
+import DocCardList from '@theme/DocCardList';
+import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
+
+<DocCardList items={useCurrentSidebarCategory().items}/>
+\`\`\`
+      `;
+            const tagMdTemplate = template
+                ? fs_1.default.readFileSync(template).toString()
+                : `---
+id: {{{id}}}
+title: {{{description}}}
+description: {{{description}}}
+---
+
+{{{markdown}}}
+
+\`\`\`mdx-code-block
+import DocCardList from '@theme/DocCardList';
+import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
+
+<DocCardList items={useCurrentSidebarCategory().items}/>
+\`\`\`
       `;
             loadedApi.map(async (item) => {
-                const markdown = item.type === "api" ? (0, markdown_1.createApiPageMD)(item) : (0, markdown_1.createInfoPageMD)(item);
+                const markdown = item.type === "api"
+                    ? (0, markdown_1.createApiPageMD)(item)
+                    : item.type === "info"
+                        ? (0, markdown_1.createInfoPageMD)(item)
+                        : (0, markdown_1.createTagPageMD)(item);
                 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 = infoBasePath;
                 }
                 const view = (0, mustache_1.render)(mdTemplate, item);
+                const utils = (0, mustache_1.render)(infoMdTemplate, item);
+                // eslint-disable-next-line testing-library/render-result-naming-convention
+                const tagUtils = (0, mustache_1.render)(tagMdTemplate, item);
                 if (item.type === "api") {
                     if (!fs_1.default.existsSync(`${outputDir}/${item.id}.api.mdx`)) {
                         try {
@@ -97,13 +198,26 @@ sidebar_class_name: "{{{api.method}}} api-method"
                 }
                 // TODO: determine if we actually want/need this
                 if (item.type === "info") {
-                    if (!fs_1.default.existsSync(`${outputDir}/index.api.mdx`)) {
+                    if (!fs_1.default.existsSync(`${outputDir}/${item.id}.info.mdx`)) {
+                        try {
+                            (sidebarOptions === null || sidebarOptions === void 0 ? void 0 : sidebarOptions.categoryLinkSource) === "info" // Only use utils template if set to "info"
+                                ? fs_1.default.writeFileSync(`${outputDir}/${item.id}.info.mdx`, utils, "utf8")
+                                : fs_1.default.writeFileSync(`${outputDir}/${item.id}.info.mdx`, view, "utf8");
+                            console.log(chalk_1.default.green(`Successfully created "${outputDir}/${item.id}.info.mdx"`));
+                        }
+                        catch (err) {
+                            console.error(chalk_1.default.red(`Failed to write "${outputDir}/${item.id}.info.mdx"`), chalk_1.default.yellow(err));
+                        }
+                    }
+                }
+                if (item.type === "tag") {
+                    if (!fs_1.default.existsSync(`${outputDir}/${item.id}.tag.mdx`)) {
                         try {
-                            fs_1.default.writeFileSync(`${outputDir}/index.api.mdx`, view, "utf8");
-                            console.log(chalk_1.default.green(`Successfully created "${outputDir}/index.api.mdx"`));
+                            fs_1.default.writeFileSync(`${outputDir}/${item.id}.tag.mdx`, tagUtils, "utf8");
+                            console.log(chalk_1.default.green(`Successfully created "${outputDir}/${item.id}.tag.mdx"`));
                         }
                         catch (err) {
-                            console.error(chalk_1.default.red(`Failed to write "${outputDir}/index.api.mdx"`), chalk_1.default.yellow(err));
+                            console.error(chalk_1.default.red(`Failed to write "${outputDir}/${item.id}.tag.mdx"`), chalk_1.default.yellow(err));
                         }
                     }
                 }
@@ -119,11 +233,13 @@ sidebar_class_name: "{{{api.method}}} api-method"
     async function cleanApiDocs(options) {
         const { outputDir } = options;
         const apiDir = path_1.default.join(siteDir, outputDir);
-        const apiMdxFiles = await (0, utils_1.Globby)(["*.api.mdx"], {
+        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) {
@@ -142,18 +258,48 @@ sidebar_class_name: "{{{api.method}}} api-method"
             }
         }));
     }
+    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) {
@@ -162,21 +308,71 @@ sidebar_class_name: "{{{api.method}}} api-method"
                     }
                 }
                 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) {
@@ -188,7 +384,46 @@ sidebar_class_name: "{{{api.method}}} api-method"
                     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/createAuthentication.d.ts

@@ -0,0 +1,2 @@
+import { SecuritySchemeObject } from "../openapi/types";
+export declare function createAuthentication(securitySchemes: SecuritySchemeObject): string;