OpenAPITools / OpenAPITools/openapi-generator

[REQ] Support per-file template data for supporting files

Open
#15,085 4 comments 0 reactions 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.

Encountered this need with the typescript-angular client generator (already extended by me) but in theory it is independent from the generated language.
Use case: Want to output generated models in different directories ("domains") according to a vendor extension tag used in the specification file.

Standard generator outputs all models in one directory and generates a models.ts file (barrel file) through which the models are exported. If splitting up in multiple directories we need multiple barrel files which is possible by adding several SupportingFiles. Additionally, those files should only output the models which are in that directory and not all of them. So each SupportingFile needs its own list of models for that.

This is currently not possible because the bundle (from buildSupportFileBundle) only contains global data and it is not possible to pass individual data to a SupportingFile.

I have resorted to extending SupportingFile to be able to pass individual data to it and then adding that data to the bundle so that it is available in the template. However, that required me to extend DefaultGenerator which is problematic because plugins like the Gradle plugin invoke DefaultGenerator and have no capability to invoke other generators (I think).

Describe the solution you'd like

One solution would be if the possibility to pass individual data to a SupportingFile would be available in core. For that

  • SupportingFile would get an additional field e.g. a HashMap variables to hold individual data and associated constructors and methods for handling this with full backwards compatibility (i.e. if you do not use the additional field there are no changes in behavior).
  • DefaultGenerator in generateSupportingFiles would take data from SupportingFile and adds it to the bundle as e.g. templateVariables. It takes care that data is cleaned up after each templating run to avoid data leaking to other SupportingFiles.
  • one would be able to access individual data in a Mustache template by accessing e.g. {{ templateVariables.hashMapKey }}.

Downside here is that somebody who wants to add data per SupportFile has to do so in the right place. That means after the needed data is available and before the templating occurs compared to just having a defined place where supporting files are added. However, it is also possible to define supporting files at the usual place and then modify them again when some data should be added.

Describe alternatives you've considered

If the above is undesirable other possibilities would be

  • call a method in DefaultGenerator.generateSupportingFiles before calling processTemplateToFile on this.config that receives the SupportingFile and the bundle that can add data to the bundle based on the current SupportingFile. After the processTemplateToFile call then there would be another similar method that is able to clean up the added data to the bundle again. Problem: if that second method is not implemented properly data might leak between files.
  • provide the possibility to use generators extended from DefaultGenerator in plugins such as the Gradle plugin (so that one could achieve this by oneself) by adding a configuration parameter to configure the instantiated generator class. Problem: cleanup is difficult with that approach and portions of DefaultGenerator might need to be copied which impacts maintenance. So it might be valuable to make DefaultGenerator better extendable at the same time.

Additional context

I might have missed other possibilities to solve this. Also ones that are able to achieve it without changing core.
I'm happy to provide PRs for any of the described solutions.

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

Start by reading SupportingFile and DefaultGenerator, especially buildSupportFileBundle and generateSupportingFiles around processTemplateToFile. Compare the proposed per-file variables and cleanup alternatives, then verify that each supporting template receives its own data without leaking values to subsequent files.

Written by the indexing model from the issue text.

Assessment

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.