docusaurus-plugin-openapi-docs 4.2.0 → 4.3.0

package/README.md

@@ -41,7 +41,7 @@ Key Features:
 
 | Docusaurus OpenAPI Docs | Docusaurus      |
 | ----------------------- | --------------- |
-| 4.0.x (current)         | `3.5.0 - 3.5.2` |
+| 4.0.x (current)         | `3.5.0 - 3.6.x` |
 | 3.0.x (end-of-support)  | `3.0.1 - 3.4.0` |
 | 2.2.3 (legacy)          | `2.4.1 - 2.4.3` |
 | 1.7.3 (end-of-support)  | `2.0.1 - 2.2.0` |
@@ -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:

package/lib/index.d.ts

@@ -1,5 +1,5 @@
 import type { LoadContext, Plugin } from "@docusaurus/types";
-import type { PluginOptions, LoadedContent } from "./types";
+import type { LoadedContent, PluginOptions } from "./types";
 export declare function isURL(str: string): boolean;
 export declare function getDocsPluginConfig(presetsPlugins: any[], plugin: string, pluginId: string): Object | undefined;
 declare function pluginOpenAPIDocs(context: LoadContext, options: PluginOptions): Plugin<LoadedContent>;

package/lib/index.js

@@ -409,6 +409,52 @@ custom_edit_url: null
             });
         }
     }
+    async function generateAllVersions(options, pluginId) {
+        const parentOptions = Object.assign({}, options);
+        const { versions } = parentOptions;
+        if (versions != null && Object.keys(versions).length > 0) {
+            const version = parentOptions.version;
+            const label = parentOptions.label;
+            const baseUrl = parentOptions.baseUrl;
+            let parentVersion = {};
+            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_1.default.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) {
+        const parentOptions = Object.assign({}, options);
+        const { versions } = parentOptions;
+        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`,
         extendCli(cli) {
@@ -418,10 +464,12 @@ 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) => {
                 var _a;
                 const options = instance.opts();
                 const pluginId = options.pluginId;
+                const allVersions = options.allVersions;
                 const pluginInstances = getPluginInstances(plugins);
                 let targetConfig;
                 let targetDocsPluginId;
@@ -450,6 +498,9 @@ custom_edit_url: null
                     else {
                         Object.keys(targetConfig).forEach(async function (key) {
                             await generateApiDocs(targetConfig[key], targetDocsPluginId);
+                            if (allVersions) {
+                                await generateAllVersions(targetConfig[key], targetDocsPluginId);
+                            }
                         });
                     }
                 }
@@ -458,6 +509,9 @@ custom_edit_url: null
                 }
                 else {
                     await generateApiDocs(targetConfig[id], targetDocsPluginId);
+                    if (allVersions) {
+                        await generateAllVersions(targetConfig[id], targetDocsPluginId);
+                    }
                 }
             });
             cli
@@ -542,10 +596,12 @@ 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) => {
                 var _a;
                 const options = instance.opts();
                 const pluginId = options.pluginId;
+                const allVersions = options.allVersions;
                 const pluginInstances = getPluginInstances(plugins);
                 let targetConfig;
                 if (pluginId) {
@@ -572,11 +628,17 @@ 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]);
+                    }
                 }
             });
             cli

package/lib/markdown/createAuthentication.js

@@ -28,11 +28,11 @@ function createAuthentication(securitySchemes) {
                         (0, utils_1.create)("th", { children: `OAuth Flow (${flowType}):` }),
                         (0, utils_1.create)("td", {
                             children: [
-                                (0, utils_1.guard)(tokenUrl, () => (0, utils_1.create)("p", { children: `Token URL: ${tokenUrl}` })),
-                                (0, utils_1.guard)(authorizationUrl, () => (0, utils_1.create)("p", {
+                                (0, utils_1.guard)(tokenUrl, () => (0, utils_1.create)("div", { children: `Token URL: ${tokenUrl}` })),
+                                (0, utils_1.guard)(authorizationUrl, () => (0, utils_1.create)("div", {
                                     children: `Authorization URL: ${authorizationUrl}`,
                                 })),
-                                (0, utils_1.guard)(refreshUrl, () => (0, utils_1.create)("p", { children: `Refresh URL: ${refreshUrl}` })),
+                                (0, utils_1.guard)(refreshUrl, () => (0, utils_1.create)("div", { children: `Refresh URL: ${refreshUrl}` })),
                                 (0, utils_1.create)("span", { children: "Scopes:" }),
                                 (0, utils_1.create)("ul", {
                                     children: Object.entries(scopes).map(([scope, description]) => (0, utils_1.create)("li", { children: `${scope}: ${description}` })),

package/lib/markdown/createTermsOfService.js

@@ -24,7 +24,7 @@ function createTermsOfService(termsOfService) {
             }),
             (0, utils_1.create)("a", {
                 href: `${termsOfService}`,
-                children: termsOfService,
+                children: `{'${termsOfService}'}`,
             }),
         ],
     });

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "docusaurus-plugin-openapi-docs",
   "description": "OpenAPI plugin for Docusaurus.",
-  "version": "4.2.0",
+  "version": "4.3.0",
   "license": "MIT",
   "keywords": [
     "openapi",
@@ -28,7 +28,10 @@
     "watch": "tsc --watch"
   },
   "devDependencies": {
+    "@docusaurus/plugin-content-docs": "^3.5.0",
     "@docusaurus/types": "^3.5.0",
+    "@docusaurus/utils": "^3.5.0",
+    "@docusaurus/utils-validation": "^3.5.0",
     "@types/fs-extra": "^9.0.13",
     "@types/json-pointer": "^1.0.31",
     "@types/json-schema": "^7.0.9",
@@ -38,9 +41,6 @@
   },
   "dependencies": {
     "@apidevtools/json-schema-ref-parser": "^11.5.4",
-    "@docusaurus/plugin-content-docs": "^3.5.0",
-    "@docusaurus/utils": "^3.5.0",
-    "@docusaurus/utils-validation": "^3.5.0",
     "@redocly/openapi-core": "^1.10.5",
     "allof-merge": "^0.6.6",
     "chalk": "^4.1.2",
@@ -57,10 +57,13 @@
     "xml-formatter": "^2.6.1"
   },
   "peerDependencies": {
+    "@docusaurus/plugin-content-docs": "^3.5.0",
+    "@docusaurus/utils": "^3.5.0",
+    "@docusaurus/utils-validation": "^3.5.0",
     "react": "^16.8.4 || ^17.0.0 || ^18.0.0"
   },
   "engines": {
     "node": ">=14"
   },
-  "gitHead": "e7295a8aa6f3fab5ccc4f8f9ad0e6c33d785aa16"
+  "gitHead": "e16e2f912a3da02444d1755b6d350deadd62185f"
 }

package/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]);
+            }
           }
         });
 

package/src/markdown/createAuthentication.ts

@@ -35,15 +35,15 @@ export function createAuthentication(securitySchemes: SecuritySchemeObject) {
             create("td", {
               children: [
                 guard(tokenUrl, () =>
-                  create("p", { children: `Token URL: ${tokenUrl}` })
+                  create("div", { children: `Token URL: ${tokenUrl}` })
                 ),
                 guard(authorizationUrl, () =>
-                  create("p", {
+                  create("div", {
                     children: `Authorization URL: ${authorizationUrl}`,
                   })
                 ),
                 guard(refreshUrl, () =>
-                  create("p", { children: `Refresh URL: ${refreshUrl}` })
+                  create("div", { children: `Refresh URL: ${refreshUrl}` })
                 ),
                 create("span", { children: "Scopes:" }),
                 create("ul", {

package/src/markdown/createTermsOfService.ts

@@ -23,7 +23,7 @@ export function createTermsOfService(termsOfService: string | undefined) {
       }),
       create("a", {
         href: `${termsOfService}`,
-        children: termsOfService,
+        children: `{'${termsOfService}'}`,
       }),
     ],
   });