[REQ] Provide templating authoring details in config-help or generate CLI command (or subcommands of generate)

[jimschubert]

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-help is 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-files might 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).

[jimschubert]

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:

• simulate or dry-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 details
• info: can display a list of info on supporting files, vendor extensions, additional properties, or anything else which is heavily reliant on processOpts. 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 on generate now.
• author or extend: 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-help

I don't know if airline supports group options, though.

[jimschubert]

See also #4976

[jimschubert]

Feature set documentation is available via #4941 and #5188
Standardization of vendor extensions is available via #5295
The --dry-run option as recommended in #4976 is available via #5332

Additional things I'd like to explore for this feature:

• A command to make authoring easier for users (extracting all files from the jar to some output location)
  • via [cli] new 'author template' command #6441
• A CLI option to dump vendor extensions and values, available on dry-run or normal generation (object type such as API/Model and path would need to be considered)
• A CLI option to dump a list of supporting files