Added an --all-versions flag to gen-api-docs and clean-api-docs (#1018)

* Added --all-versions flag to gen-api-docs and clean-api-docs to avoid having to know which apis have versions

* Cleaned up in prep for PR

* Updated docs

.gitignore

@@ -142,3 +142,4 @@ demo/**/sidebar.ts
 demo/**/versions.json
 
 .idea
+.tool-versions

README.md

@@ -269,6 +269,16 @@ yarn docusaurus gen-api-docs petstore
 
 > The example above will only generate API docs relative to `petstore`.
 
+If you have multiple versions of the same API, `gen-api-docs` only generates the latest. To generate all versions, use the `--all-versions` flag.
+
+Example:
+
+```bash
+yarn docusaurus gen-api-docs all --all-versions
+```
+
+> This will generate API docs for all versions of all the OpenAPI specification (OAS) files referenced in your `docusaurus-plugin-openapi-docs` config.
+
 ### Cleaning API Docs
 
 To clean/remove all API Docs, run the following command from the root directory of your project:
@@ -291,6 +301,16 @@ yarn docusaurus clean-api-docs petstore
 
 > The example above will remove all API docs relative to `burgers`.
 
+If you have multiple versions of the same API, `clean-api-docs` only cleans the latest. To clean all versions, use the `--all-versions` flag.
+
+Example:
+
+```bash
+yarn docusaurus clean-api-docs all --all-versions
+```
+
+> This will clean API docs for all versions of all the OpenAPI specification (OAS) files referenced in your `docusaurus-plugin-openapi-docs` config.
+
 ### Versioning OpenAPI docs
 
 To generate _all_ versioned OpenAPI docs, run the following command from the root directory of your project:

demo/package.json

@@ -16,9 +16,9 @@
     "clean-api-docs": "docusaurus clean-api-docs",
     "gen-api-docs:version": "docusaurus gen-api-docs:version",
     "clean-api-docs:version": "docusaurus clean-api-docs:version",
-    "gen-all": "docusaurus gen-api-docs all && docusaurus gen-api-docs:version petstore_versioned:all",
-    "clean-all": "docusaurus clean-api-docs all && docusaurus clean-api-docs:version petstore_versioned:all",
-    "re-gen": "yarn clean-all && yarn gen-all"
+    "gen-all": "docusaurus gen-api-docs all --all-versions",
+    "clean-all": "docusaurus clean-api-docs all --all-versions",
+    "re-gen": "yarn clean-all-versions && yarn gen-all-versions"
   },
   "dependencies": {
     "@docusaurus/core": "3.6.1",

package.json

@@ -24,8 +24,8 @@
     "canaryBeta:publish": "yarn lerna publish from-package --dist-tag canary --yes --no-verify-access",
     "serve": "yarn workspace demo serve",
     "start": "yarn workspace demo start",
-    "gen-api": "yarn workspace demo gen-api-docs all",
-    "clean-api": "yarn workspace demo clean-api-docs all",
+    "gen-api": "yarn workspace demo gen-api-docs all --all-versions",
+    "clean-api": "yarn workspace demo clean-api-docs all --all-versions",
     "cy:run": "cypress run",
     "cy:open": "cypress open",
     "format": "prettier . --check --ignore-unknown --ignore-path .prettierignore",

packages/docusaurus-plugin-openapi-docs/README.md

@@ -268,6 +268,16 @@ yarn docusaurus gen-api-docs petstore
 
 > The example above will only generate API docs relative to `petstore`.
 
+If you have multiple versions of the same API, `gen-api-docs` only generates the latest. To generate all versions, use the `--all-versions` flag.
+
+Example:
+
+```bash
+yarn docusaurus gen-api-docs all --all-versions
+```
+
+> This will generate API docs for all versions of all the OpenAPI specification (OAS) files referenced in your `docusaurus-plugin-openapi-docs` config.
+
 ### Cleaning API Docs
 
 To clean/remove all API Docs, run the following command from the root directory of your project:
@@ -290,6 +300,16 @@ yarn docusaurus clean-api-docs petstore
 
 > The example above will remove all API docs relative to `burgers`.
 
+If you have multiple versions of the same API, `clean-api-docs` only cleans the latest. To clean all versions, use the `--all-versions` flag.
+
+Example:
+
+```bash
+yarn docusaurus clean-api-docs all --all-versions
+```
+
+> This will clean API docs for all versions of all the OpenAPI specification (OAS) files referenced in your `docusaurus-plugin-openapi-docs` config.
+
 ### Versioning OpenAPI docs
 
 To generate _all_ versioned OpenAPI docs, run the following command from the root directory of your project:

packages/docusaurus-plugin-openapi-docs/src/index.ts

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