OpenAPITools / OpenAPITools/openapi-generator

[REQ] More detailed documentation for custom templates

Open
#6,442 1 comment 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

Enhancement: Feature
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.

I spent a few hours today trying and failing to get the generator (5.0.0-SNAPSHOT) with typescript-axios to load a custom template overload. It just ignored the local directory path I provided with the -t option and didn't offer any error message warning me that my input was wrong.

Generally, the custom templates documentation is confusing.

I'd led to believe, based on the following quote (emphasis added), that I'm able to just specify plain, local, uncompiled directories of mustache template files as a template directory argument:

OpenAPI Generator not only supports local files for templating, but also templates defined on the classpath.

However no examples of the former case, "local files for templating," is actually presented in the documentation. Instead I'm shown examples of how I can provide compiled jar files with magical keyword path references, which is outside the scope of what I'd like to do right now.

Describe the solution you'd like

I'm trying to avoid the magic and compilation and everything which is why I didn't go straight into building my own custom generator, so I'd love to have some clear docs telling me how to point to some mustache file overrides for an existing generator without needing to compile anything. Or if the docs were incorrect and I do need to compile something, I'd love everything to be spelled out for me like I'm dumb. 😄

Describe alternatives you've considered

Additional context

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

Review the custom templates section at the linked templating documentation page, focusing on the -t option and the typescript-axios generator. Document how to use local, uncompiled Mustache overrides, or clearly explain if compilation is required, with an example and the expected behavior for an invalid path.

Written by the indexing model from the issue text.

Assessment

Tech stack
java, openapi, typescript
Domain
documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.