jimschubert
commented
4 years ago Vendor Extensions, Supporting Files may make more sense as a --dry-run option for the generate command or something similar. Features should be doable once #3614 is merged, and I envision either outputting a table to the generator doc page or creating an overall matrix like kangax's ES6 compat page (https://kangax.github.io/compat-table/es6/) or jwt.io' library option support display (https://jwt.io/).
I've output most of the details for modifying a generator via config help changes in #4941. These options (primitives, import/instantiation mapping) make sense as part of config-help because they are CLI options which may need to be modified to generate valid code, especially for specs users don't control.
Authoring details may make more sense as its own command. Authoring is a more advanced option which might require viewing or dumping template files for a given generator+library combination, with instructions for modifying the template. This could get hairy because some generators switch on options provided to the generate command to determine which files are added to the supporting files array.
I wonder if it may make more sense to create "subcommand" for the generate command. In airline, there aren't really subcommands, so it would require that we change generate to a group, with a default command of run. This would allow us to put the additional functionality here under commands like:
simulateordry-run: acts as a dry-run, and displays a list of files which would have been written, files which would have been excluded (and why), or other detailsinfo: can display a list of info on supporting files, vendor extensions, additional properties, or anything else which is heavily reliant onprocessOpts. I don't know how airline shares args between commands within a group, but I think an info subcommand would have the same requirements as we have ongeneratenow.authororextend: could be used to add options for writing out templates for users. Rather than expecting users to go to github, pull code, checkout the tag for their version, then find the appropriate folder, copying everything in the same/correct hierarchy to some local directory and extending files individually... the author command could dump those files and provide a short explanation of usage.
If we go the subcommand route, we could also consider having config-help as a subcommand. This might look like:
openapi-generator generate -g kotlin config-helpI don't know if airline supports group options, though.
Is your feature request related to a problem? Please describe.
Yes. The barrier to entry for authoring templates or custom generators should be minimized.
Describe the solution you'd like
config-help should provide some options for displaying more than CLI-only generation flags.
Examples:
--authoring=> could provide the embeddedTemplateDir as this isn't always the same as the generator name--extensions=> could provide a list of vendor extensions for the generator--supporting-files=> could provide a list of the supporting files.--features=> could list the features supported by the generator (OAuth, JSON/XML, API Key, etc)Describe alternatives you've considered
We could create a new CLI command, but that seems to add little value over one or more additional switches.
Additional context
I think any additional information should be hidden by default. That is, authoring and extension information shouldn't display when
config-helpis called for a generator without the additional switches. This is because some of our generators have a ton of options, and there's no need to crowd the terminal output.The
--supporting-filesmight be non-trivial because many generators conditionally add supporting files based on CLI options passed to the generator. I think we would need to update generators to "register" supporting files and associate them to the options which would lead to those files being generated.The generated output could eventually be used to generate parts of our documentation (see #1770).