Added an --all-versions flag to gen-api-docs and clean-api-docs

[dv-stewarts]

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 all to 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 the docusaurus gen... command, so instead I'm proposing this PR, which adds a -all-versions flag to docusaurus gen-api-docs and docusaurus clean-api-docs to 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-all and clean-all scripts 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

• New feature (non-breaking change which adds functionality)

Checklist

• I have updated the documentation accordingly.
• I have read the CONTRIBUTING document.
• I have added tests to cover my changes if appropriate.
• All new and existing tests passed.
  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.

[sserrata]

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!

[sserrata]

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.

[sserrata]

Update: I went ahead and opened facebook/docusaurus#10681

[dv-stewarts]

Thanks @sserrata. I doubt my change could have broken that, but since I, at best, dabble with javascript, anything is possible.

[github-actions]

Visit the preview URL for this PR (updated for commit bb7a97f):

https://docusaurus-openapi-36b86--pr1018-6f0gui85.web.app

_{(expires Sun, 15 Dec 2024 17:50:58 GMT)}

_{🔥 via Firebase Hosting GitHub Action 🌎}

_{Sign: bf293780ee827f578864d92193b8c2866acd459f}

[dv-stewarts]

@sserrata I see docusaurus have closed facebook/docusaurus#10681 Do you think this can be merged in?

[sserrata]

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.

[sserrata]

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.

[sserrata]

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.

[dv-stewarts]

@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!