OpenAPITools / OpenAPITools/openapi-generator
[BUG] No info in the docs about modifying a template
Nobody has claimed this yet.
- Dominant language
- Java
- Stars
- 26.8k
- Forks
- 7.7k
- PR merge metrics
- PR metrics pending
Description
Hi. I've read README.md and almost all the files from the docs/ directory and yet I haven't seen any instructions on how to modify a template file, which is in fact - covers 90% of use cases (according to the docs themselves).
Suprisingly, the templating.md which might explain the matter, discusses some niche cases, while leaving aside the templating itself.
The same applies to the customization.md which speaks verbosely about creating new generators, but misses the part about templating.
And the faq*.md just references above files.
Is this a sort of a quest? :) Or a kind of some superinability to see things which really needs clarification? Kidding, sorry.
Let me share my thoughts then.
Let's assume, one decides to customize a template. First what they would need is to get the unmodified, original templates. Say the 'nodejs-express-server` is set as a target. Now:
- Is there a command which creates a folder with the original templates? (Having
metaat our disposal I would assume it to also create a templates dir. See? I know aboutmetabut I haven't learned how to modify a mere template :) ) - If there isn't - then how to locate the original files in the source tree?
- Can one override just few template while removing the rest, so that it would be served from the defaults?
- Should one maintain some specific directory structure under
-t my-templates-dirto get things working or one can basically drop files into there?
Have I expreimented yet? Sorry, no, but about to start! I just hoped to read some docs first. (You see recently I've got a sort of a bad experience with this... set of contraptions, having my head banging against the wall trying to get the same things working with so called Swagger. This is my pathetic ticket: https://github.com/swagger-api/swagger-codegen/issues/10107)
Sorry if anything, didn't mean to be rude. But I admit, I was not ready for such ordeals when decided to modify one pitty line in one generated file about a week ago. I really didn't expect it would take SO much time.
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 README.md, docs/templating.md, docs/customization.md, and the faq*.md files first, then inspect how the nodejs-express-server target handles -t and meta. Document where original templates are found, the expected template directory structure, and how partial overrides and defaults work; done means a newcomer can modify one template without searching the source.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- express, node.js
- Domain
- documentation, tooling
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100