OpenAPITools / OpenAPITools/openapi-generator

[BUG] No info in the docs about modifying a template

Open
#5,654 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Issue: Bug
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 meta at our disposal I would assume it to also create a templates dir. See? I know about meta but 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-dir to 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

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.