OpenAPITools / OpenAPITools/openapi-generator
[REQ] More detailed documentation for custom templates
Nobody has claimed this yet.
- 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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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