OpenAPITools / OpenAPITools/openapi-generator

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

Open
#1,811 3 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

Enhancement: Feature OpenAPI Generator CLI
Dominant language
Java
Stars
26.8k
Forks
7.7k
PR merge metrics
PR metrics pending

Description

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).

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Begin with the existing config-help and generate CLI entry points, then trace how generator metadata and conditional supporting files are represented. Define how authoring, extensions, supporting-files, and features should be exposed while remaining hidden by default. Done means the chosen CLI design provides this information without unnecessarily expanding normal config-help output, with documentation generation from the output considered alongside #1770.

Written by the indexing model from the issue text.

Assessment

Tech stack
java
Domain
cli, tooling
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
30/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.