[REQ][Java] Remove unused imports from generated Java code #25145

Is your feature request related to a problem? Please describe.

Generated Java code very often contains unused (and sometimes duplicated) imports. Apart from being a code smell that IDEs and linters flag in every generated file, it has caused real problems:

• [BUG][JAVA] Unused Locale Imports #22313: an unused import java.util.Locale clashes with a model named Locale and breaks compilation.
• [BUG] [JAVA] Unused Import Requires Its Own Dependency #18289: an unused import requires an additional dependency just to compile.
• [BUG] [spring] [server] 5.0.1 unused imports in generated interfaces #8776, [BUG] Unused JsonNullable imports #16931, [BUG][JAVA] Generating native Java models with AllOf/OneOf definitions without creating client creates a model with unused imports #23700, [BUG][JAVA] Unused Locale Imports #22313 were all reported/fixed one import at a time.

To get an idea of the scale, I ran a simple analysis over the committed samples (an import counts as unused when its simple name does not occur as an identifier in the code, outside of comments and string literals):

Examples from the current samples:

import java.util.HashMap;
import java.util.List;
import java.util.Locale;   // <-- unused
import java.util.Map;
import java.util.Objects;   // <-- unused
import java.util.Arrays;   // <-- unused
import java.util.stream.Collectors;   // <-- unused
import org.springframework.core.io.FileSystemResource;   // <-- unused

import java.util.Objects;
import java.util.Arrays;   // <-- duplicate
...
import java.util.ArrayList;
import java.util.Arrays;   // <-- duplicate
...
import com.fasterxml.jackson.annotation.JsonTypeName;   // <-- unused
import com.fasterxml.jackson.annotation.JsonIgnore;   // <-- unused

import java.net.URI;   // <-- unused
import com.fasterxml.jackson.annotation.JsonCreator;   // <-- unused
import java.time.OffsetDateTime;   // <-- unused
import jakarta.validation.Valid;   // <-- unused
import tools.jackson.dataformat.xml.annotation.JacksonXmlElementWrapper;   // <-- unused

Where they come from. Imports reach a generated file from two sources:

1. {{#imports}}import {{import}};{{/imports}}, computed by the codegen (fromModel/fromOperation/postProcessModelProperty, ...). Some are added unconditionally, e.g. importMapping.put("com.fasterxml.jackson.annotation.JsonProperty", "com.fasterxml.jackson.annotation.JsonCreator") in AbstractJavaCodegen, or Nullable added to every Spring model. For APIs it is the union over all operations of a tag.
2. Hard-coded import lines in the templates, mostly unconditional or only guarded by coarse flags (e.g. all swagger2 annotations in JavaSpring/api.mustache, Locale/Objects/Arrays/Collectors/FileSystemResource in the restclient/webclient api.mustache, URI/OffsetDateTime in JavaSpring/model.mustache).

For the Spring Boot 4 spring, restclient and webclient samples, 480 of 494 unused imports come from hard-coded template lines (2.), only 14 from the computed imports (1.). Duplicates appear where both sources import the same class.

Describe the solution you'd like

A generic, opt-in post-processing step that removes unused imports from generated Java sources, applied to the rendered template output before it is written to disk:

• A new hook in CodegenConfig, e.g. String postProcessTemplateOutput(String content, File target) (identity by default in DefaultCodegen), called in TemplateManager.write between compileTemplate and writeToFile. Doing it there keeps minimalUpdate and skipOverwrite working, and it applies to models, APIs and supporting files alike, including user-provided custom templates.
• A small dependency-free import pruner used by AbstractJavaCodegen for .java targets, enabled by a new option (e.g. removeUnusedImports):
  • removes single-type and static imports whose simple name never occurs as an identifier in the code (comments and string literals stripped), and duplicate imports;
  • keeps wildcard imports and imports only referenced from Javadoc (e.g. {@link Foo});
  • optionally also drops imports whose simple name equals a type declared in the same file (always a compile error, see [BUG][JAVA] Unused Locale Imports #22313).

This is safe for compilation by construction: a single-type import only introduces its simple name, so if the name is not used, removing the import cannot change the meaning of the code. As a sanity check, I applied this logic to copies of the springboot-4, springboot-4-jspecify-useOptional, restclient-springBoot4-jackson3 and webclient-springBoot4-jackson3 samples: 285 imports were removed, and all of them still compile.

Possible rollout: introduce the option disabled by default (enabled e.g. in the Spring Boot 4 spring/restclient/webclient sample configs) to keep the sample diff reviewable, and enable it by default later, e.g. in a minor release. Other generators (e.g. Kotlin) could reuse the same hook with their own pruner later.

Describe alternatives you've considered

• Fixing templates/codegen import by import (what has been done so far, e.g. [Java] Use Fully Qualified Name for java.util.Locale in Generated Classes #22342). It doesn't scale: many imports would need per-file "is it used" conditions (e.g. "does any operation of this tag use ExampleObject"), across many templates/libraries, it regresses easily, and doesn't help custom templates. Still worth doing for the obviously wrong codegen-side imports, but as a complement.
• External formatter via JAVA_POST_PROCESS_FILE (e.g. google-java-format --fix-imports-only). Already possible, but opt-in, requires external tooling, spawns a process per file, and runs after the file is written (so it doesn't play well with minimalUpdate/skipOverwrite).
• JavaParser-based pruning. JavaParser is already a dependency, but the current version (3.24.9) cannot parse sealed/permits (generated by useSealed), and re-printing the AST risks formatting changes. A lexical approach is simpler and sufficient for this purpose.

Additional context

Before working on a PR, I'd like to know whether this is something the maintainers would be interested in, and if so:

1. Is a new CodegenConfig hook in TemplateManager.write acceptable, or is there a preferred place?
2. Should the option be opt-in first (and on by default later), or on by default right away (large sample diff across all Java generators)?
3. Any preference on the option name (removeUnusedImports)?

I'm happy to implement it, starting with the Spring Boot 4 spring, restclient and webclient generators.