-
Notifications
You must be signed in to change notification settings - Fork 293
Added an --all-versions flag to gen-api-docs and clean-api-docs #1018
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Added an --all-versions flag to gen-api-docs and clean-api-docs #1018
Conversation
... having to know which apis have versions
Hi @dv-stewarts, thanks for the contribution. I haven't had time to test but I think the approach should work. Will try to take a look either this or early next week. Thanks!
Hi @dv-stewarts, while I was reviewing your branch I noticed something: the running yarn docusaurus --help no longer includes the extended commands introduced by docusaurus-plugin-openapi-docs. I don't think it's anything specific to your changes but definitely changed between v2 and v3. I checked the most recent docs on extendCli and didn't see anything different about the usage.
For example:
Before (v2)
$ docusaurus -h
Usage: docusaurus <command> [options]
Options:
-V, --version output the version number
-h, --help display help for command
Commands:
build [options] [siteDir] Build website.
swizzle [options] [themeName] [componentName] [siteDir] Wraps or ejects the original theme files into website folder for customization.
deploy [options] [siteDir] Deploy website to GitHub pages.
start [options] [siteDir] Start the development server.
serve [options] [siteDir] Serve website locally.
clear [siteDir] Remove build artifacts.
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 [options] <id> Generates OpenAPI docs in MDX file format and sidebar.js (if enabled).
gen-api-docs:version [options] <id:version> Generates versioned OpenAPI docs in MDX file format, versions.js and sidebar.js (if enabled).
clean-api-docs [options] <id> Clears the generated OpenAPI docs MDX files and sidebar.js (if enabled).
clean-api-docs:version [options] <id:version> Clears the versioned, generated OpenAPI docs MDX files, versions.json and sidebar.js (if enabled).
Current (v3)
$ docusaurus -h
Usage: docusaurus <command> [options]
Options:
-V, --version output the version number
-h, --help display help for command
Commands:
build [options] [siteDir] Build website.
swizzle [options] [themeName] [componentName] [siteDir] Wraps or ejects the original theme files into website folder for customization.
deploy [options] [siteDir] Deploy website to GitHub pages.
start [options] [siteDir] Start the development server.
serve [options] [siteDir] Serve website locally.
clear [siteDir] Remove build artifacts.
write-translations [options] [siteDir] Extract required translations of your site.
write-heading-ids [options] [siteDir] [files...] Generate heading ids in Markdown content.
Update: I went ahead and opened facebook/docusaurus#10681
Thanks @sserrata. I doubt my change could have broken that, but since I, at best, dabble with javascript, anything is possible.
Visit the preview URL for this PR (updated for commit bb7a97f):
https://docusaurus-openapi-36b86--pr1018-6f0gui85.web.app
(expires 2024年12月15日 17:50:58 GMT)
🔥 via Firebase Hosting GitHub Action 🌎
Sign: bf293780ee827f578864d92193b8c2866acd459f
@sserrata I see docusaurus have closed facebook/docusaurus#10681 Do you think this can be merged in?
Hey @dv-stewarts, yes I saw that. I suppose we could use the latest canary release from Docusaurus to test - just want to make sure the help output/usage looks good before proceeding. I suppose we could also just pass a bogus command since the error output appears to include the extended commands.
Ah, since it's a command option, and not a command, it does show after all:
docusaurus-openapi-docs/demo all_versions_flag yarn docusaurus clean-api-docs -h
yarn run v1.22.19
$ docusaurus clean-api-docs -h
Usage: docusaurus clean-api-docs <id>
Clears the generated OpenAPI docs MDX files and sidebar.ts (if enabled).
Options:
-p, --plugin-id <plugin> OpenAPI docs plugin ID.
--all-versions Clean all versions.
-h, --help display help for command
✨ Done in 1.99s.
docusaurus-openapi-docs/demo all_versions_flag yarn gen-api-docs -h
yarn run v1.22.19
$ docusaurus gen-api-docs -h
Usage: docusaurus gen-api-docs <id>
Generates OpenAPI docs in MDX file format and sidebar.ts (if enabled).
Options:
-p, --plugin-id <plugin> OpenAPI docs plugin ID.
--all-versions Generate all versions.
-h, --help display help for command
✨ Done in 2.23s.
Question...just to clarify behavior, the idea is that --all-versions will work with either all or a key referencing a versioned API, e.g. petstore_versioned, but NOT a non-versioned key, e.g. petstore. Is that correct?
In summary:
yarn docusaurus gen-api-docs petstore --all-versions❌yarn docusaurus gen-api-docs petstore_versioned --all-versions✅yarn docusaurus gen-api-docs all --all-versions✅
Very minor issue, but I noticed that when you use the option with non-versioned key/API it neither throws an error/warning nor generates versioned docs.
@sserrata I think the intention was to generate all versions, regardless of if versions exist or not. If there is only one version, then generating non-versioned docs seems to me like the behavior that was requested.
Either way, thanks for merging!
Description
Added an --all-versions flag to gen-api-docs and clean-api-docs in order to be able to generate all versions of all apis without having to individually specify each api you would like to generate all versions of.
Motivation and Context
I am trying to build a docker image of docusaurus + openapi-docs into which I can mount any arbitrary docs folder + api specs and it will detect all the apis present and generate docs for them. I do this using a function in docusaurus.config.ts. When starting the docker container it runs
docusaurus gen-api-docs allto generate the docs. Unfortunately this only generates the current version of each api and not the historical versions. I couldn't think of a way to make the list of apis available to thedocusaurus gen...command, so instead I'm proposing this PR, which adds a-all-versionsflag todocusaurus gen-api-docsanddocusaurus clean-api-docsto support this use case.I think it's also a QOL improvement as I find having to generate versions separately from the docs is a bit aggravating.
How Has This Been Tested?
I ran
tests. It passes.I ran
tests:cypress. It doesn't pass, but it didn't pass for me on main either.I replaced the
gen-allandclean-allscripts which generate all docs and then specifically generate all versions for petstore_versioned with this flag and compared the outputted files from the two using mtree. There were no differences.I'm not much a javascript developer, so I wasn't sure what more I could/should be doing. Happy to receive feedback/suggestions.
I don't believe my change will impact any other parts of the code.
Screenshots (if appropriate)
n/a
Types of changes
Checklist
I couldn't get existing tests to pass on main and I'm not sure what other tests would be appropriate as I couldn't find any existing tests for the cli.