OpenAPITools / OpenAPITools/openapi-generator

[REQ] Add filesDir config option for directory-based template discovery

Open
#23,877 1 comment 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.

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 corresponding templateType
  • Unrecognized subdirectory names become SupportingFiles with the directory path as the output folder
  • .mustache suffixes are stripped from the destination filename
  • filesDir and files can be used together; explicit files entries take precedence on conflict
Describe alternatives you've considered
  1. Listing every file under files — works but doesn't scale; requires keeping config and template directory in sync manually.
  2. Writing a custom generator via meta — the processOpts() method in a custom CodegenConfig subclass can programmatically scan a directory and call supportingFiles.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) — the getFiles() method is extended to also scan filesDir and return the merged list of TemplateDefinition objects
  • No changes needed to CodegenConfigurator, DefaultGenerator, TemplateDefinition, TemplateFileType, or any CLI classes — the entire downstream pipeline already works with List<TemplateDefinition> generically
  • Fully backward compatible — filesDir is optional and the existing files behavior is unchanged

I have a PR ready with the implementation, tests (5 new test cases), and documentation.

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.