Problem statement
Generated Java sources produced through OpenAPI Generics inherit a significant amount of source-level noise from upstream OpenAPI Generator templates.
Examples include:
- Unused imports
- Duplicate imports
- Redundant imports introduced by template inheritance
- Imports that become unnecessary after wrapper reconstruction
- Formatting inconsistencies in generated artifacts
Examples:
import java.util.Arrays;
import java.util.Arrays;
import com.fasterxml.jackson.annotation.JsonCreator;
import com.fasterxml.jackson.annotation.JsonTypeName;
import com.fasterxml.jackson.annotation.JsonValue;
inside classes that do not reference those types.
The generated code remains functionally correct and compiles successfully, but generated artifacts contain avoidable noise that reduces readability and increases maintenance effort.
This issue is not specific to:
- wrapper reconstruction
- container support
- vendor extensions
- external model registration
The root cause originates from generated source artifacts themselves.
OpenAPI Generics already owns a generation orchestration layer through openapi-generics-java-codegen-parent, but that orchestration currently stops after generation and source registration.
No generated-source hygiene phase exists.
Proposed solution
Introduce a generated-source hygiene phase into the Java code generation orchestration pipeline.
Current flow:
OpenAPI Generator
↓
Template overlays
↓
Generated sources
↓
Compilation
Proposed flow:
OpenAPI Generator
↓
Template overlays
↓
Generated sources
↓
Generated source hygiene
↓
Compilation
The hygiene phase may perform tasks such as:
- unused import removal
- duplicate import removal
- import normalization
- source formatting
- future generated-source cleanup operations
The implementation should remain pluggable and implementation-agnostic.
Possible implementations include:
- Spotless
- OpenRewrite
- future source-cleanup providers
The objective is not import cleanup itself.
The objective is establishing a deterministic generated-source hygiene stage within the OpenAPI Generics generation lifecycle.
Alternatives considered
Continue adjusting templates
Attempt to remove unnecessary imports directly within custom templates.
Rejected because the problem is broader than OpenAPI Generics templates and originates from upstream OpenAPI Generator output as well.
Add import cleanup logic into code generation
Introduce additional generator-specific logic for import management.
Rejected because source cleanup is a post-generation concern rather than a code generation concern.
Keep current behavior
Leave generated artifacts unchanged.
Rejected because generated sources become increasingly noisy as templates evolve and additional generation features are introduced.
Expected impact
- Cleaner generated Java sources
- Removal of duplicate imports
- Removal of unused imports
- Improved readability of generated artifacts
- Reduced template maintenance burden
- Better generated artifact quality
- Cleaner repository diffs
- No impact on runtime behavior
- No impact on projection or reconstruction semantics
Additional context
OpenAPI Generics already provides a dedicated generation orchestration layer through:
openapi-generics-java-codegen-parent
This makes generated-source hygiene a natural orchestration concern rather than a template concern.
The proposal does not introduce new generation capabilities.
It introduces a post-generation quality stage that improves generated artifact quality while keeping projection, reconstruction, vendor extensions, and runtime behavior unchanged.
Status
Fixed on main and currently available in 1.2.0-SNAPSHOT.
Planned for the next public release.
Implementation reference:
b6d0068
Problem statement
Generated Java sources produced through OpenAPI Generics inherit a significant amount of source-level noise from upstream OpenAPI Generator templates.
Examples include:
Examples:
inside classes that do not reference those types.
The generated code remains functionally correct and compiles successfully, but generated artifacts contain avoidable noise that reduces readability and increases maintenance effort.
This issue is not specific to:
The root cause originates from generated source artifacts themselves.
OpenAPI Generics already owns a generation orchestration layer through
openapi-generics-java-codegen-parent, but that orchestration currently stops after generation and source registration.No generated-source hygiene phase exists.
Proposed solution
Introduce a generated-source hygiene phase into the Java code generation orchestration pipeline.
Current flow:
Proposed flow:
The hygiene phase may perform tasks such as:
The implementation should remain pluggable and implementation-agnostic.
Possible implementations include:
The objective is not import cleanup itself.
The objective is establishing a deterministic generated-source hygiene stage within the OpenAPI Generics generation lifecycle.
Alternatives considered
Continue adjusting templates
Attempt to remove unnecessary imports directly within custom templates.
Rejected because the problem is broader than OpenAPI Generics templates and originates from upstream OpenAPI Generator output as well.
Add import cleanup logic into code generation
Introduce additional generator-specific logic for import management.
Rejected because source cleanup is a post-generation concern rather than a code generation concern.
Keep current behavior
Leave generated artifacts unchanged.
Rejected because generated sources become increasingly noisy as templates evolve and additional generation features are introduced.
Expected impact
Additional context
OpenAPI Generics already provides a dedicated generation orchestration layer through:
This makes generated-source hygiene a natural orchestration concern rather than a template concern.
The proposal does not introduce new generation capabilities.
It introduces a post-generation quality stage that improves generated artifact quality while keeping projection, reconstruction, vendor extensions, and runtime behavior unchanged.
Status
Fixed on
mainand currently available in1.2.0-SNAPSHOT.Planned for the next public release.
Implementation reference:
b6d0068