OpenAPITools / OpenAPITools/openapi-generator
[REQ] Add filesDir config option for directory-based template discovery
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.
When using the files config option to add custom template files, every single file must be listed individually in the YAML/JSON configuration. For projects with many additional templates, this quickly becomes unwieldy and error-prone:
files:
README.mustache:
folder: ''
destinationFilename: README.md
validators.mustache:
templateType: Model
destinationFilename: .ts
api_interfaces.mustache:
templateType: API
destinationFilename: Interface.kt
api_impl.mustache:
templateType: API
destinationFilename: Impl.kt
build.gradle.mustache:
folder: scripts
destinationFilename: build.gradle
templateType: SupportingFiles
# ... 20 more entries ...
Every time you add or remove a template file, you must also update the config. There is no way to say "use all files in this directory."
Describe the solution you'd like
A new filesDir config option that points to a directory. The generator scans it and auto-registers every file found, using subdirectory names to determine the templateType:
templateDir: my_custom_templates
filesDir: my_extra_templates/
Where the directory structure follows this convention:
my_extra_templates/
README.md # -> SupportingFiles (root = default)
LICENSE.mustache # -> SupportingFiles, output as "LICENSE"
api/
custom_api.mustache # -> templateType: API
model/
validators.mustache # -> templateType: Model
apiDocs/
api_readme.mustache # -> templateType: APIDocs
modelDocs/
model_readme.mustache # -> templateType: ModelDocs
apiTests/
api_test.mustache # -> templateType: APITests
modelTests/
model_test.mustache # -> templateType: ModelTests
supportingFiles/
build.gradle.mustache # -> SupportingFiles
scripts/
check.sh # -> SupportingFiles, folder: "scripts"
custom_output_dir/
deploy.sh # -> SupportingFiles, folder: "custom_output_dir"
Rules:
- Root files default to
SupportingFiles - Recognized subdirectory names (case-insensitive:
api,model,apiDocs,modelDocs,apiTests,modelTests,supportingFiles) map to the correspondingtemplateType - Unrecognized subdirectory names become
SupportingFileswith the directory path as the outputfolder .mustachesuffixes are stripped from the destination filenamefilesDirandfilescan be used together; explicitfilesentries take precedence on conflict
Describe alternatives you've considered
- Listing every file under
files— works but doesn't scale; requires keeping config and template directory in sync manually. - Writing a custom generator via
meta— theprocessOpts()method in a customCodegenConfigsubclass can programmatically scan a directory and callsupportingFiles.add(...). This works but is a massive escalation in complexity (requires a separate Java/Maven project, compilation, classpath management) for what should be a simple config option.
Additional context
The implementation is small and low-risk:
- The change is confined to
DynamicSettings.java(~80 lines of new code) — thegetFiles()method is extended to also scanfilesDirand return the merged list ofTemplateDefinitionobjects - No changes needed to
CodegenConfigurator,DefaultGenerator,TemplateDefinition,TemplateFileType, or any CLI classes — the entire downstream pipeline already works withList<TemplateDefinition>generically - Fully backward compatible —
filesDiris optional and the existingfilesbehavior is unchanged
I have a PR ready with the implementation, tests (5 new test cases), and documentation.
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
Start in DynamicSettings.java, especially getFiles(), and review the five new test cases and related documentation mentioned in the issue. Done means directory-based templates are discovered with the stated type and folder rules, explicit files take precedence, and existing files behavior remains unchanged.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- java
- Domain
- tooling
- Issue type
- Feature
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 48/100