From 6ad497bb10d552b69e5a9183ae997094b02c523c Mon Sep 17 00:00:00 2001 From: dv-stewarts <117725019+dv-stewarts@users.noreply.github.com> Date: Mon, 18 Nov 2024 20:40:12 +0100 Subject: [PATCH] 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 | 1 + README.md | 20 +++++ demo/package.json | 6 +- package.json | 4 +- .../docusaurus-plugin-openapi-docs/README.md | 20 +++++ .../src/index.ts | 89 +++++++++++++++++-- 6 files changed, 130 insertions(+), 10 deletions(-) diff --git a/.gitignore b/.gitignore index 10e42b734..fd1c0d0b6 100644 --- a/.gitignore +++ b/.gitignore @@ -142,3 +142,4 @@ demo/**/sidebar.ts demo/**/versions.json .idea +.tool-versions diff --git a/README.md b/README.md index 0f75d3de6..62b4b73b8 100644 --- a/README.md +++ b/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: diff --git a/demo/package.json b/demo/package.json index 860bac9d9..f03ced1a8 100644 --- a/demo/package.json +++ b/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", diff --git a/package.json b/package.json index f870f605d..ced12e092 100644 --- a/package.json +++ b/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", diff --git a/packages/docusaurus-plugin-openapi-docs/README.md b/packages/docusaurus-plugin-openapi-docs/README.md index 409c89ef3..8e5e801fe 100644 --- a/packages/docusaurus-plugin-openapi-docs/README.md +++ b/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: diff --git a/packages/docusaurus-plugin-openapi-docs/src/index.ts b/packages/docusaurus-plugin-openapi-docs/src/index.ts index e7cb7a537..61a84e0ac 100644 --- a/packages/docusaurus-plugin-openapi-docs/src/index.ts +++ b/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("") .arguments("") .option("-p, --plugin-id ", "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("") .arguments("") .option("-p, --plugin-id ", "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]); + } } });