From 1f400115a4669ae420995a1e1d807105274eae4a Mon Sep 17 00:00:00 2001 From: Stewart Southern Date: Fri, 8 Nov 2024 13:09:14 +0100 Subject: [PATCH 1/3] Added --all-versions flag to gen-api-docs and clean-api-docs to avoid having to know which apis have versions --- .gitignore | 1 + demo/package.json | 9 +- .../src/index.ts | 90 +++++++++++++++++-- yarn.lock | 41 ++------- 4 files changed, 100 insertions(+), 41 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/demo/package.json b/demo/package.json index e45d26595..865e259ae 100644 --- a/demo/package.json +++ b/demo/package.json @@ -16,9 +16,12 @@ "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-old": "docusaurus gen-api-docs all && docusaurus gen-api-docs:version petstore_versioned:all", + "gen-all": "docusaurus gen-api-docs all --all-versions", + "clean-all-old": "docusaurus clean-api-docs all && docusaurus clean-api-docs:version petstore_versioned:all", + "clean-all": "docusaurus clean-api-docs all --all-versions", + "re-gen-old": "yarn clean-all && yarn gen-all", + "re-gen": "yarn clean-all-versions && yarn gen-all-versions" }, "dependencies": { "@docusaurus/core": "3.6.0", diff --git a/packages/docusaurus-plugin-openapi-docs/src/index.ts b/packages/docusaurus-plugin-openapi-docs/src/index.ts index e7cb7a537..ac4316b5c 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,12 @@ 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; + console.log("allVersions", allVersions); const pluginInstances = getPluginInstances(plugins); let targetConfig: any; let targetDocsPluginId: any; @@ -637,6 +700,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 +714,9 @@ custom_edit_url: null ); } else { await generateApiDocs(targetConfig[id], targetDocsPluginId); + if (allVersions) { + await generateAllVersions(targetConfig[id], targetDocsPluginId); + } } }); @@ -748,9 +820,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 +858,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]); + } } }); diff --git a/yarn.lock b/yarn.lock index 0c8a51871..174fedb85 100644 --- a/yarn.lock +++ b/yarn.lock @@ -2293,7 +2293,7 @@ utility-types "^3.10.0" webpack "^5.88.1" -"@docusaurus/plugin-content-docs@3.6.0": +"@docusaurus/plugin-content-docs@3.6.0", "@docusaurus/plugin-content-docs@^3.5.0": version "3.6.0" resolved "https://registry.yarnpkg.com/@docusaurus/plugin-content-docs/-/plugin-content-docs-3.6.0.tgz#15cae4bf81da0b0ddce09d53b10b7209116ea9c2" integrity sha512-c5gZOxocJKO/Zev2MEZInli+b+VNswDGuKHE6QtFgidhAJonwjh2kwj967RvWFaMMk62HlLJLZ+IGK2XsVy4Aw== @@ -2439,7 +2439,7 @@ tslib "^2.6.0" utility-types "^3.10.0" -"@docusaurus/theme-common@3.6.0": +"@docusaurus/theme-common@3.6.0", "@docusaurus/theme-common@^3.5.0": version "3.6.0" resolved "https://registry.yarnpkg.com/@docusaurus/theme-common/-/theme-common-3.6.0.tgz#9a061d278df76da0f70a9465cd0b7299c14d03d3" integrity sha512-frjlYE5sRs+GuPs4XXlp9aMLI2O4H5FPpznDAXBrCm+8EpWRiIb443ePMxM3IyMCQ5bwFlki0PI9C+r4apstnw== @@ -2487,7 +2487,7 @@ fs-extra "^11.1.1" tslib "^2.6.0" -"@docusaurus/types@3.6.0": +"@docusaurus/types@3.6.0", "@docusaurus/types@^3.5.0": version "3.6.0" resolved "https://registry.yarnpkg.com/@docusaurus/types/-/types-3.6.0.tgz#8fa82332a7c7b8093b5c55e1115f5854ce484978" integrity sha512-jADLgoZGWhAzThr+mRiyuFD4OUzt6jHnb7NRArRKorgxckqUBaPyFOau9hhbcSTHtU6ceyeWjN7FDt7uG2Hplw== @@ -2509,7 +2509,7 @@ dependencies: tslib "^2.6.0" -"@docusaurus/utils-validation@3.6.0": +"@docusaurus/utils-validation@3.6.0", "@docusaurus/utils-validation@^3.5.0": version "3.6.0" resolved "https://registry.yarnpkg.com/@docusaurus/utils-validation/-/utils-validation-3.6.0.tgz#5557ca14fa64ac29e6f70e61006be721395ecde5" integrity sha512-CRHiKKJEKA0GFlfOf71JWHl7PtwOyX0+Zg9ep9NFEZv6Lcx3RJ9nhl7p8HRjPL6deyYceavM//BsfW4pCI4BtA== @@ -2523,7 +2523,7 @@ lodash "^4.17.21" tslib "^2.6.0" -"@docusaurus/utils@3.6.0": +"@docusaurus/utils@3.6.0", "@docusaurus/utils@^3.5.0": version "3.6.0" resolved "https://registry.yarnpkg.com/@docusaurus/utils/-/utils-3.6.0.tgz#192785da6fd62dfd83d6f1879c3aa45547f5df23" integrity sha512-VKczAutI4mptiAw/WcYEu5WeVhQ6Q1zdIUl64SGw9K++9lziH+Kt10Ee8l2dMpRkiUk6zzK20kMNlX2WCUwXYQ== @@ -17232,16 +17232,7 @@ string-natural-compare@^3.0.1: resolved "https://registry.yarnpkg.com/string-natural-compare/-/string-natural-compare-3.0.1.tgz#7a42d58474454963759e8e8b7ae63d71c1e7fdf4" integrity sha512-n3sPwynL1nwKi3WJ6AIsClwBMa0zTi54fn2oLU6ndfTSIO05xaznjSf15PcBZU6FNWbmN5Q6cxT4V5hGvB4taw== -"string-width-cjs@npm:string-width@^4.2.0": - version "4.2.3" - resolved "https://registry.yarnpkg.com/string-width/-/string-width-4.2.3.tgz#269c7117d27b05ad2e536830a8ec895ef9c6d010" - integrity sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g== - dependencies: - emoji-regex "^8.0.0" - is-fullwidth-code-point "^3.0.0" - strip-ansi "^6.0.1" - -"string-width@^1.0.2 || 2 || 3 || 4", string-width@^4.1.0, string-width@^4.2.0, string-width@^4.2.3: +"string-width-cjs@npm:string-width@^4.2.0", "string-width@^1.0.2 || 2 || 3 || 4", string-width@^4.1.0, string-width@^4.2.0, string-width@^4.2.3: version "4.2.3" resolved "https://registry.yarnpkg.com/string-width/-/string-width-4.2.3.tgz#269c7117d27b05ad2e536830a8ec895ef9c6d010" integrity sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g== @@ -17361,7 +17352,7 @@ stringify-object@3.3.0, stringify-object@^3.3.0: is-obj "^1.0.1" is-regexp "^1.0.0" -"strip-ansi-cjs@npm:strip-ansi@^6.0.1": +"strip-ansi-cjs@npm:strip-ansi@^6.0.1", strip-ansi@^6.0.0, strip-ansi@^6.0.1: version "6.0.1" resolved "https://registry.yarnpkg.com/strip-ansi/-/strip-ansi-6.0.1.tgz#9e26c63d30f53443e9489495b2105d37b67a85d9" integrity sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A== @@ -17375,13 +17366,6 @@ strip-ansi@^5.0.0, strip-ansi@^5.1.0, strip-ansi@^5.2.0: dependencies: ansi-regex "^4.1.0" -strip-ansi@^6.0.0, strip-ansi@^6.0.1: - version "6.0.1" - resolved "https://registry.yarnpkg.com/strip-ansi/-/strip-ansi-6.0.1.tgz#9e26c63d30f53443e9489495b2105d37b67a85d9" - integrity sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A== - dependencies: - ansi-regex "^5.0.1" - strip-ansi@^7.0.1: version "7.1.0" resolved "https://registry.yarnpkg.com/strip-ansi/-/strip-ansi-7.1.0.tgz#d5b6568ca689d8561370b0707685d22434faff45" @@ -18923,7 +18907,7 @@ wordwrap@^1.0.0: resolved "https://registry.yarnpkg.com/wordwrap/-/wordwrap-1.0.0.tgz#27584810891456a4171c8d0226441ade90cbcaeb" integrity sha512-gvVzJFlPycKc5dZN4yPkP8w7Dc37BtP1yczEneOb4uq34pXZcvrtRTmWV8W+Ume+XCxKgbjM+nevkyFPMybd4Q== -"wrap-ansi-cjs@npm:wrap-ansi@^7.0.0": +"wrap-ansi-cjs@npm:wrap-ansi@^7.0.0", wrap-ansi@^7.0.0: version "7.0.0" resolved "https://registry.yarnpkg.com/wrap-ansi/-/wrap-ansi-7.0.0.tgz#67e145cff510a6a6984bdf1152911d69d2eb9e43" integrity sha512-YVGIj2kamLSTxw6NsZjoBxfSwsn0ycdesmc4p+Q21c5zPuZ1pl+NfxVdxPtdHvmNVOQ6XSYG4AUtyt/Fi7D16Q== @@ -18950,15 +18934,6 @@ wrap-ansi@^6.0.1, wrap-ansi@^6.2.0: string-width "^4.1.0" strip-ansi "^6.0.0" -wrap-ansi@^7.0.0: - version "7.0.0" - resolved "https://registry.yarnpkg.com/wrap-ansi/-/wrap-ansi-7.0.0.tgz#67e145cff510a6a6984bdf1152911d69d2eb9e43" - integrity sha512-YVGIj2kamLSTxw6NsZjoBxfSwsn0ycdesmc4p+Q21c5zPuZ1pl+NfxVdxPtdHvmNVOQ6XSYG4AUtyt/Fi7D16Q== - dependencies: - ansi-styles "^4.0.0" - string-width "^4.1.0" - strip-ansi "^6.0.0" - wrap-ansi@^8.0.1, wrap-ansi@^8.1.0: version "8.1.0" resolved "https://registry.yarnpkg.com/wrap-ansi/-/wrap-ansi-8.1.0.tgz#56dc22368ee570face1b49819975d9b9a5ead214" From 697ba45be9693ce080c40280faf86ffd135988f3 Mon Sep 17 00:00:00 2001 From: Stewart Southern Date: Fri, 8 Nov 2024 14:52:44 +0100 Subject: [PATCH 2/3] Cleaned up in prep for PR --- demo/package.json | 3 --- package.json | 4 ++-- packages/docusaurus-plugin-openapi-docs/src/index.ts | 1 - 3 files changed, 2 insertions(+), 6 deletions(-) diff --git a/demo/package.json b/demo/package.json index 865e259ae..fafaeb27e 100644 --- a/demo/package.json +++ b/demo/package.json @@ -16,11 +16,8 @@ "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-old": "docusaurus gen-api-docs all && docusaurus gen-api-docs:version petstore_versioned:all", "gen-all": "docusaurus gen-api-docs all --all-versions", - "clean-all-old": "docusaurus clean-api-docs all && docusaurus clean-api-docs:version petstore_versioned:all", "clean-all": "docusaurus clean-api-docs all --all-versions", - "re-gen-old": "yarn clean-all && yarn gen-all", "re-gen": "yarn clean-all-versions && yarn gen-all-versions" }, "dependencies": { 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/src/index.ts b/packages/docusaurus-plugin-openapi-docs/src/index.ts index ac4316b5c..61a84e0ac 100644 --- a/packages/docusaurus-plugin-openapi-docs/src/index.ts +++ b/packages/docusaurus-plugin-openapi-docs/src/index.ts @@ -663,7 +663,6 @@ custom_edit_url: null const options = instance.opts(); const pluginId = options.pluginId; const allVersions = options.allVersions; - console.log("allVersions", allVersions); const pluginInstances = getPluginInstances(plugins); let targetConfig: any; let targetDocsPluginId: any; From 0b5c4dcbe865e8039d2f545392605b36bca7e5f2 Mon Sep 17 00:00:00 2001 From: Stewart Southern Date: Fri, 8 Nov 2024 15:32:38 +0100 Subject: [PATCH 3/3] Updated docs --- README.md | 20 +++++++++++++++++++ .../docusaurus-plugin-openapi-docs/README.md | 20 +++++++++++++++++++ 2 files changed, 40 insertions(+) diff --git a/README.md b/README.md index 8a1d07372..4643f4dc9 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/packages/docusaurus-plugin-openapi-docs/README.md b/packages/docusaurus-plugin-openapi-docs/README.md index 7ffec67c7..e63201566 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: