Release notes from openapi-generics

v1.2.0 — Application-Defined Generic Containers and Deterministic Generated Source Hygiene

2026-06-27T14:13:17Z

This release extends the container-aware infrastructure introduced in 1.1.0 by allowing applications to register their own generic container contracts.

OpenAPI Generics can now preserve and reconstruct both built-in containers and application-defined containers through the same contract-first projection and deterministic client generation pipeline.

This release also improves projection metadata by preserving Java container identity and adds generated-source hygiene for cleaner Java client artifacts.

All 1.1.x contracts remain fully supported.

No migration is required for existing users.

What This Release Adds

Application-Defined Generic Containers

OpenAPI Generics previously supported built-in container shapes such as:

ServiceResponse<List<T>>
ServiceResponse<Set<T>>
ServiceResponse<Page<T>>

and equivalent BYOE shapes:

ApiResponse<List<T>>
ApiResponse<Set<T>>
ApiResponse<Page<T>>

Version 1.2.0 allows applications to register their own generic container contracts.

Example:

openapi-generics:
  envelope:
    type: io.example.contract.ApiResponse

  containers:
    - type: io.example.contract.Paging
      item-property: content

    - type: io.example.contract.Window
      item-property: items

These containers participate in the same projection and reconstruction pipeline as built-in List<T>, Set<T>, and platform Page<T> containers.

Example supported shapes now include:

ApiResponse<Paging<CustomerDto>>
ApiResponse<Window<CustomerDto>>

Configured containers are validated during startup to ensure the container contract is structurally supported.

Java Container Identity in Projection Metadata

Projection metadata now preserves the resolved Java container type through:

x-data-container-type

Built-in container example:

x-api-wrapper: true
x-api-wrapper-datatype: PageCustomerDto
x-data-container: Page
x-data-container-type: io.github.blueprintplatform.openapi.generics.contract.paging.Page
x-data-item: CustomerDto

Application-defined container example:

x-api-wrapper: true
x-api-wrapper-datatype: PagingCustomerDto
x-data-container: Paging
x-data-container-type: io.example.contract.Paging
x-data-item: CustomerDto

This makes container metadata more explicit and deterministic while preserving backward compatibility with the existing x-data-container and x-data-item model.

Generated-Source Hygiene

The Java code generation parent now includes a deterministic generated-source hygiene phase.

After generation, OpenAPI Generics cleans generated Java sources by removing duplicate and unused imports and applying consistent formatting.

This improves generated artifact quality without changing contract semantics or runtime behavior.

The generation lifecycle now becomes:

OpenAPI Generator
        ↓
Template overlays
        ↓
Generated sources
        ↓
Generated-source hygiene
        ↓
Compilation

Platform Improvements

Added application-defined generic container registration through openapi-generics.containers.
Added startup validation for configured generic containers.
Added configurable item-property support for custom container contracts.
Added x-data-container-type projection metadata.
Preserved Java container identity across introspection, projection, and reconstruction.
Unified built-in and configured containers under the same descriptor model.
Added generated-source hygiene to the Java client generation parent.
Removed duplicate and unused generated Java imports deterministically.
Updated README, GitHub Pages documentation, module documentation, compatibility policy, security policy, and contributing guidance for 1.2.0.
Expanded type coverage samples for BYOE and application-defined generic containers.

Quality & Verification

Added regression coverage for configured container registration and validation.
Added metadata validation for x-data-container-type.
Added projection and reconstruction coverage for Paging<T> and Window<T> sample containers.
Added generated-source hygiene verification.
Verified producer → OpenAPI → generated client → consumer flows for:
- built-in containers
- BYOE envelopes
- application-defined generic containers
Verified backward compatibility with all 1.1.x response contracts.

Compatibility

Fully backward compatible with all 1.1.x releases.

Supported platforms:

Java 17+
Spring Boot 3.x
Spring Boot 4.x
OpenAPI Generator 7.x
Maven-based client generation

Impact

No migration required
No breaking contract changes
Application-owned generic containers are now supported
Projection metadata is more explicit and deterministic
Generated Java clients are cleaner and easier to inspect
BYOE scenarios are significantly more flexible
Contract-first architecture remains unchanged

Closed Issues

#27 Preserve Java container type in projection metadata
#28 Introduce generated-source hygiene phase
#29 Support application-defined generic containers

Summary

v1.2.0 turns the container model introduced in 1.1.0 into an extensible platform capability.

The release adds:

configurable application-defined generic containers
Java container identity preservation through x-data-container-type
deterministic generated-source hygiene
expanded BYOE type coverage
updated documentation and release guidance

while keeping all existing 1.1.x contracts fully compatible.

v1.1.0 — Container-Aware Generic Infrastructure and Deterministic Contract Validation

2026-06-21T15:42:37Z

This release introduces the first major capability expansion since the 1.0.0 GA release.

OpenAPI Generics now supports container-aware contract reconstruction through a dedicated generic container infrastructure and introduces deterministic OpenAPI specification validation across sample projects.

All 1.0.x contracts remain fully supported.

No migration is required for existing users.

What This Release Adds

Container-Aware Generic Infrastructure

OpenAPI Generics previously focused on canonical response shapes such as:

ServiceResponse<T>
ServiceResponse<Page<T>>

Version 1.1.0 introduces a dedicated container model that treats generic containers as a first-class platform capability.

Supported response shapes now include:

ServiceResponse<T>
ServiceResponse<List<T>>
ServiceResponse<Set<T>>
ServiceResponse<Page<T>>

The same capability is available for custom BYOE envelopes:

ApiResponse<T>
ApiResponse<List<T>>
ApiResponse<Set<T>>
ApiResponse<Page<T>>

Container handling is now resolved through shared metadata rather than container-specific implementations.

Unified Projection and Reconstruction

Container metadata now participates consistently across:

Java Contract
        ↓
Projection
        ↓
OpenAPI Schema
        ↓
Vendor Extensions
        ↓
Code Generation
        ↓
Runtime Reconstruction

This eliminates container-specific branching and establishes a single reconstruction model for supported generic response types.

Generated wrapper examples:

ServiceResponseCustomerDto
ServiceResponseListCustomerDto
ServiceResponseSetCustomerDto
ServiceResponsePageCustomerDto

ApiResponseCustomerDto
ApiResponseListCustomerDto
ApiResponseSetCustomerDto
ApiResponsePageCustomerDto

All wrappers are reconstructed through the same container-aware infrastructure.

Deterministic OpenAPI Snapshot Validation

Generated OpenAPI specifications are now treated as validation artifacts.

Sample projects now:

generate OpenAPI specifications during validation
commit deterministic specification snapshots
validate projection metadata through automated assertions
detect specification drift through CI verification

This makes projection changes visible immediately and significantly reduces regression risk when evolving projection logic, metadata generation, schema naming, or reconstruction behavior.

Type Coverage Expansion

Validation coverage has been expanded across both canonical and BYOE contracts.

Covered scenarios include:

ServiceResponse<T>
ServiceResponse<List<T>>
ServiceResponse<Set<T>>
ServiceResponse<Page<T>>

ApiResponse<T>
ApiResponse<List<T>>
ApiResponse<Set<T>>
ApiResponse<Page<T>>

Validation includes:

scalar payloads
value payloads
enum payloads
DTO payloads
collection payloads
paged payloads
generated client reconstruction
runtime deserialization
consumer integration

All scenarios are verified through producer → OpenAPI → generated client → consumer pipelines.

Platform Improvements

Introduced extensible generic container metadata model.
Unified container handling across projection and generation.
Added descriptor-based container resolution.
Added deterministic OpenAPI snapshot verification.
Added specification drift detection to CI validation.
Reorganized sample hierarchy and aggregators.
Expanded architecture, adoption, compatibility, and release documentation.
Updated all project documentation for the 1.1.0 release line.

Compatibility

Fully backward compatible with all 1.0.x releases.

Supported platforms:

Java 17+
Spring Boot 3.x
Spring Boot 4.x
OpenAPI Generator 7.x
Maven-based client generation

Impact

No migration required
No breaking contract changes
Expanded supported generic response shapes
BYOE nested container support
Stronger projection guarantees
Deterministic specification validation
Improved long-term maintainability of projection and reconstruction logic

Closed Issues

#24 Introduce extensible generic container infrastructure
#25 Establish deterministic OpenAPI specification validation

Summary

v1.1.0 expands OpenAPI Generics from a Page-oriented generic reconstruction model into a container-aware platform architecture.

The release introduces:

extensible generic container support
List, Set, and Page reconstruction
BYOE container support
deterministic OpenAPI snapshot validation
expanded end-to-end verification coverage

while preserving the contract-first architecture and backward compatibility established in the 1.0.x GA line.

v1.0.3 — Type Coverage Validation, Platform Hardening and Generator Alignment

2026-06-13T10:25:05Z

This release is a patch-level update for the 1.0.x GA line, focusing on platform correctness, validation coverage, generation consistency, and end-to-end verification.

No contract changes.
No public API behavior changes.
No generated client structure changes.

Fully compatible with the 1.0.0, 1.0.1, and 1.0.2 GA contracts.

What This Release Improves

Generic wrapper reconstruction is now validated through dedicated type coverage suites
Direct enum payload support is formally enforced and documented
OpenAPI Generator version alignment is now deterministic across the entire generation pipeline
Ignored model handling is aligned with upstream OpenAPI Generator processing lifecycle
Spring Boot 3 and Spring Boot 4 sample verification has been refreshed and upgraded

Type Coverage Validation

This release introduces dedicated type coverage samples that verify the complete contract-to-client lifecycle.

The new validation suites cover:

Canonical ServiceResponse<T> usage
Custom BYOE response envelopes
Generic wrapper reconstruction
OpenAPI projection correctness
Generated client compatibility
End-to-end producer/client/consumer verification

These samples provide a focused environment for validating supported generic response patterns and preventing regressions in future releases.

Enum Payload Validation

Direct enum payload support is now explicitly validated.

OpenAPI Generics relies on stable OpenAPI component identities for generic wrapper reconstruction.

As a result:

Direct enum payloads are supported only when exposed as reusable OpenAPI schema components
@Schema(enumAsRef = true) is now required for enum payload reconstruction
Unsupported inline enum payloads are rejected during response type discovery
DTOs containing enum fields remain fully supported

This change enforces an existing architectural boundary rather than introducing a new capability.

Generator Consistency

Generator version alignment has been hardened across the full client-generation lifecycle.

The configured OpenAPI Generator version now consistently drives:

plugin execution
generator runtime dependencies
upstream template extraction
internal generation behavior

This removes version drift scenarios and improves reproducibility for advanced customization and generator upgrades.

Generator Lifecycle Hardening

Ignored models are now removed before upstream OpenAPI Generator global model processing begins.

This prevents intentionally excluded schemas from participating in model graph traversal and eliminates misleading warning messages during generation.

Benefits include:

cleaner generation output
improved CI/CD log quality
better alignment with upstream generator lifecycle expectations

Generated source behavior remains unchanged.

Platform & Sample Updates

Upgraded platform modules and samples to Spring Boot 3.5.15
Upgraded OpenAPI Generator alignment to 7.23.0
Upgraded Spring Boot 4 samples to Spring Boot 4.0.7
Simplified sample module structure and metadata
Expanded sample documentation and verification workflows

Quality & Verification

Added regression coverage for enum payload discovery
Added regression coverage for ignored model lifecycle handling
Added regression coverage for generator version consistency
Verified Spring Boot 3 sample pipeline
Verified Spring Boot 4 sample pipeline
Verified Docker-based sample execution
Verified end-to-end producer/client/consumer flows

Impact

No migration required
No contract changes
No generated client changes
More deterministic generation behavior
Stronger validation of supported response patterns
Improved sample-based verification coverage
Cleaner and more predictable build output

Summary

v1.0.3 is a platform hardening, validation, and verification update.

It strengthens the platform by:

validating generic response reconstruction through dedicated coverage suites
enforcing supported enum payload boundaries
eliminating generator lifecycle inconsistencies
guaranteeing generator version alignment
improving reproducibility across local, CI, and sample verification environments

Without changing the contract-first architecture introduced in 1.0.0 GA.

Closed Issues

#23 Enforce reusable enum component requirement for direct enum payloads
#22 Prevent ignored models from entering upstream global model post-processing
#21 Honor configured OpenAPI Generator version across generation pipeline

v1.0.2 — Documentation Clarity, BYOC Hardening and Verified Build Quality

2026-05-16T14:32:29Z

This release is a patch-level update for the 1.0.x GA line, focusing on documentation clarity, defensive validation, and build verification.

No contract changes.
No public API behavior changes.
No generated client structure changes.

Fully compatible with the 1.0.0 and 1.0.1 GA contracts.

What This Release Improves

Documentation now follows a clearer problem → proof → adoption flow
Server and client adoption guides are more explicit and easier to follow
BYOE and BYOC configuration semantics are clarified
External model validation is more defensive and provides better diagnostics
Sample pipelines and CI verification are more robust and reproducible

Documentation & Adoption Clarity

Reworked README and documentation site structure for faster evaluation and onboarding
Clarified server-side and client-side adoption guides
Documented that openapi-generics-server-starter runs only during Springdoc OpenAPI document generation (/v3/api-docs and CI generation)
Clarified Bring Your Own Envelope (BYOE) configuration and constraints
Clarified Bring Your Own Contract (BYOC) usage and shared-contract patterns
Clarified fallback behavior for reverting to standard OpenAPI Generator output
Improved sample documentation and run-and-verify instructions

Build & Dependency Quality

Centralized version management and strengthened parent POM alignment
Added Spotless-based source formatting to the build
Improved Docker-based sample builds for self-contained local verification
Strengthened CI workflows for snapshot and local-install validation

BYOC Hardening

External model registration is now more defensive.

Ignores null, blank, and invalid FQCN mappings
Emits clear diagnostic warnings for invalid configuration
Prevents accidental registration of malformed external model definitions

This improves reliability when reusing DTOs from shared contract modules.

Quality & Verification

Added unit tests for invalid and edge-case external model configurations
Stabilized Spring Boot 3 and Spring Boot 4 sample pipelines
Verified end-to-end Docker-based sample execution

Impact

No migration required
No behavior changes for existing users
Improved clarity of adoption and configuration
More robust BYOC diagnostics
Stronger reproducibility across local and CI builds

Summary

v1.0.2 is a documentation, diagnostics, and build quality update.

It makes the platform:

easier to understand
easier to adopt
more defensive in BYOC configuration
more reproducible across build and verification pipelines

Without changing the contract-first architecture introduced in 1.0.0 GA.

v1.0.1 — Build Hygiene, Dependency Alignment and Verified Release Stability

2026-05-01T13:26:29Z

This release is a patch-level update for the 1.0.x GA line, focusing on build correctness, dependency alignment, and release readiness.

No contract changes.
No public API behavior changes.
No generated client structure changes.

Fully compatible with the 1.0.0 GA contract.

What This Release Improves

Maven build structure is now cleanly partitioned between aggregator and modules
Plugin execution boundaries are strictly enforced
Dependency alignment is deterministic across all modules
Release pipeline is fully verified and reproducible

Build & Dependency Alignment

Refined Maven POM hygiene across all platform modules
Ensured root aggregator remains lifecycle-safe (no unintended plugin execution)
Scoped build orchestration strictly to child modules
Strengthened dependency management and explicitly controlled transitive versions
Updated OpenAPI Generator alignment to 7.22.0
Upgraded Spring Boot baseline to 3.5.14 across platform modules and samples

Template Governance (Zero-Drift Guarantee)

The platform continues to enforce a no-fork, no-drift strategy for OpenAPI Generator templates.

Upstream templates are dynamically extracted during build
A targeted, non-destructive patch injects generics-aware wrapper logic
The patch is signature-validated at build time

If upstream structure changes:

The build fails fast instead of producing invalid clients

This guarantees long-term alignment with the OpenAPI Generator 7.x line without template divergence.

Quality & Verification

Integrated JaCoCo + Codecov for coverage visibility
Added unit and edge-case coverage for:
- server-side projection
- wrapper enrichment logic
Verified full pipelines across:
- Spring Boot 3
- Spring Boot 4

Impact

No behavioral change for existing users
No migration required
Improved reliability of:
- build lifecycle
- dependency resolution
- release publishing

Summary

v1.0.1 is a release-hygiene and alignment update.

It ensures that the platform is:

structurally clean
dependency-stable
reproducible in build and release pipelines

Without altering the core contract model introduced in 1.0.0 GA.

v1.0.0 — Contract-First Generics Platform with Bring Your Own Envelope (BYOE) and End-to-End Stability

2026-04-22T20:23:26Z

This release marks the General Availability of the openapi-generics platform.

The architecture is now complete, stable, and adoption-ready.

The platform no longer defines how you should build APIs —
it adapts to how you already build them.

What This Release Establishes

Contract-first architecture is now fully enforced and stable
Custom response envelopes (BYOE) are now fully supported
External contract reuse (BYOC) is first-class
OpenAPI is strictly a projection layer (not a contract source)
The full pipeline is deterministic and validated end-to-end

Contract → Server → OpenAPI → Client → Consumer

Key Feature — BYOE (Bring Your Own Envelope)

The platform no longer requires ServiceResponse<T>.

Teams can now use their existing envelope without migration.

Server

openapi-generics:
  envelope:
    type: io.example.ApiResponse

Client (Codegen)

<additionalProperty>
  openapi-generics.envelope=io.example.ApiResponse
</additionalProperty>

Behavior

Default → ServiceResponse<T> (no change)
Configured → custom envelope fully replaces default

Scope

ApiResponse<T> ✅
ApiResponse<Page<T>> ❌ (intentionally out of scope)

What Changed

Envelope Abstraction Becomes Configurable

Introduced EnvelopeMetadataResolver
Injects:
- x-envelope-import
- x-envelope-type
api_wrapper.mustache is now fully dynamic

Result:

Envelope is no longer hardcoded — it is resolved at generation time

Server Projection Refinement

Removed class-level annotation injection from projection
Projection is now strictly:
- language-agnostic
- semantic-only
Wrapper processing is now non-destructive:
- no schema overrides
- only enrichment
Relaxed validation constraints:
- allOf no longer required

Result:

OpenAPI remains a clean projection of the contract

Codegen Alignment

Full support for BYOE in generator layer
Wrapper models dynamically extend configured envelope
External models + envelope now resolved consistently

Result:

Client generation remains deterministic under customization

Documentation Overhaul

All sample documentation rewritten to be:

minimal
action-oriented
usage-first

Removed:

narrative explanations
redundant architecture descriptions

Result:

Faster onboarding, clearer intent

Pipeline Stabilization

The full system is now verified as:

deterministic
reproducible
contract-aligned

Across:

Server projection
OpenAPI output
Client generation
Consumer integration

Impact

No forced envelope migration
Existing systems can adopt incrementally
No model duplication in clients
Clear separation of concerns:
- contract
- projection
- generation
- consumption
Reduced cognitive load for adopters

🔐 Compatibility

Component	Supported Versions
Java	17+
Spring Boot	3.x / 4.x

Context

Previous releases established:

modular platform structure
contract-first baseline
generics-aware generation
BYOC (Bring Your Own Contract)

This release completes the model by introducing:

BYOE — making the platform adaptable to existing systems

Summary

v1.0.0 is a stability and adoption release.

The platform is now:

contract-first
projection-driven
generator-aligned
envelope-agnostic

No hidden behavior.
No forced abstractions.

Just:

deterministic contracts, adaptable integration, and end-to-end alignment.

v0.9.0 — Contract-First Generics Platform, BYOC, and End-to-End Validation

2026-04-12T16:15:46Z

This release formalizes the architecture that has been evolving across previous versions.

The platform is now explicitly contract-first, supports external contract reuse (BYOC), and is validated end-to-end with real consumer modules.

This is the release where the architecture is no longer a concept — it runs.

🎯 What This Release Establishes

Contract-first generation is now explicit and enforced
External contract reuse (Bring Your Own Contract - BYOC) is now first-class
The full pipeline is proven end-to-end:

Contract → OpenAPI → Generated Client → Consumer

Both Spring Boot 3 and Spring Boot 4 stacks are validated

🔧 What Changed

Explicit Generator Activation

generatorName=java-generics-contract is now required
implicit activation removed from parent configuration

This makes generation behavior:

explicit, predictable, and debuggable

External Contract Reuse (BYOC)

Introduced openapiGenerics.responseContract.* mapping
Enabled reuse of externally owned DTOs
Prevented duplicate model generation
Ensured correct import injection in generated wrappers

This establishes:

contract ownership outside the generator, without drift

Codegen Refactoring

Generator internals were decomposed for clarity and control:

ExternalModelRegistry
ModelIgnoreDecider
ExternalImportResolver

GenericAwareJavaCodegen is now focused on orchestration only.

Spring Boot 4 Client Support

RestClient-based client generation
Jackson 3 compatibility
Fixed compile-time issues in SB4 client

Consumer Module (NEW)

Added customer-service-consumer (SB3 & SB4)
Demonstrates real client usage
Validates full pipeline integration

This provides:

executable proof that contract alignment holds in real usage

CI & Coverage Updates

Coverage scoped to sample modules
Baseline adjusted to 50%
Workflows updated for SB3 / SB4 structure

Documentation Updates

Aligned client adoption guide with explicit configuration model
Clarified generator usage
Documented contract reuse approach

📦 Impact

Client generation is now explicit and deterministic
External contract models are reused (no duplication)
Generator behavior is easier to reason about and debug
Architecture is validated with real consumer integration
Documentation reflects actual system behavior

🔐 Compatibility

Component	Supported Versions
Java	17+
Spring Boot	3.x / 4.x

🧭 Context

Previous releases established:

platform modularization
Maven Central publishing
generics-aware generation baseline

This release completes the picture by ensuring:

contract definition, projection, generation, and consumption are aligned and verifiable

🎯 Summary

v0.9.0 is an architecture consolidation release.

No shortcuts. No implicit behavior.

Just:

explicit contracts, deterministic generation, and proven end-to-end alignment.

v0.8.2 — Java 17 Baseline & Compatibility Alignment

2026-04-05T21:58:17Z

This release focuses on broadening runtime compatibility by aligning the platform to a Java 17 baseline.

No architectural changes are introduced.

This is a follow-up release to v0.8.1, which established the platform structure and Maven Central distribution.

🔧 What Changed

Java Baseline Alignment

All core modules are now:

compiled with Java 17
compatible with Java 17+ runtimes

This allows the platform to be used in:

enterprise environments still on Java 17
newer runtimes (Java 21, 25+) without restriction

📦 Impact

no changes to public API
no changes to contract semantics
no changes to OpenAPI generation behavior
no changes to client generation

Only:

compilation baseline is lowered for wider adoption

🔐 Compatibility

Component	Supported Versions
Java	17+

🧭 Context

Release 0.8.1 introduced:

platform modularization
Maven Central publishing
contract-first architecture

This release ensures that foundation is:

accessible to a broader Java ecosystem

🎯 Summary

v0.8.2 is a compatibility refinement release.

No new features. No behavioral changes.

Just:

wider reach, same architecture.

v0.8.1 — Platform Modularization & Maven Central Publishing

2026-04-04T17:03:14Z

OpenAPI Generics v0.8.1 — Platform Modularization & Maven Central Publishing

Release 0.8.1 marks the point where the project transitions from a reference implementation into a publishable, dependency-driven platform.

All core capabilities are now packaged as modular artifacts and available on Maven Central, enabling direct adoption without copying code or maintaining local templates.

Define your contract once. Depend on the platform. Generate clients deterministically.

✨ Highlights

📦 Maven Central Publishing (First-Class Distribution)

All platform modules are now published and versioned:

io.github.blueprint-platform
version: 0.8.x

Available artifacts:

openapi-generics
openapi-generics-contract
openapi-generics-server-starter
openapi-generics-java-codegen
openapi-generics-java-codegen-parent
openapi-generics-platform-bom

This establishes the platform as a consumable dependency, not a codebase to replicate.

🧱 Platform Modularization (Clear Ownership Boundaries)

The system is now decomposed into independently versioned modules with explicit responsibilities:

Contract → openapi-generics-contract
Projection (OpenAPI) → openapi-generics-server-starter
Generation → openapi-generics-java-codegen
Build orchestration → openapi-generics-java-codegen-parent
Dependency alignment → openapi-generics-platform-bom

Ownership is no longer implicit.

Contract defines truth → OpenAPI represents it → Generator reconstructs it.

🚀 Dependency-Based Usage (No Copying, No Templates)

The platform is designed for direct integration via dependencies.

Server (producer)

<dependency>
  <groupId>io.github.blueprint-platform</groupId>
  <artifactId>openapi-generics-server-starter</artifactId>
  <version>0.8.x</version>
</dependency>

Client (consumer)

<parent>
  <groupId>io.github.blueprint-platform</groupId>
  <artifactId>openapi-generics-java-codegen-parent</artifactId>
  <version>0.8.x</version>
</parent>

That’s it.

Everything else in this repository is a reference implementation of this setup.

🧱 First-Class Canonical Contract (SSOT)

The response model is now a dedicated artifact:

openapi-generics-contract

It defines:

ServiceResponse<T> as the canonical envelope
Page<T> and pagination primitives
a consistent RFC 9457-aligned error model

The contract is now explicit and reusable.

It is the single source of truth (SSOT) across all layers.

⚙️ Deterministic OpenAPI Projection Pipeline

OpenAPI generation is implemented as a single orchestrated pipeline:

Discovery → Introspection → Wrapper Processing → Ignore Marking → Validation

Guarantees:

deterministic output (same input → same OpenAPI)
single execution path (no fragmented lifecycle)
fail-fast validation
framework isolation (MVC/WebFlux via strategy)

🧩 Contract-Aware Client Generation

Client generation is now aligned with the contract, not template hacks.

Behavior:

contract-owned models are never generated
x-ignore-model is enforced
only thin wrapper types are emitted
imports bind directly to canonical types

Example:

public class ServiceResponsePageCustomerDto
    extends ServiceResponse<Page<CustomerDto>> {}

Result:

generics preserved end-to-end
zero duplication
stable type system

🚫 Elimination of Generation Hacks

Removed completely:

.openapi-generator-ignore
DTO cleanup steps
formatter-based import fixes
scattered template overrides

Replaced by:

contract ownership
projection-time semantics
generator-level enforcement

No post-processing. No cleanup. No hidden behavior.

🧠 Vendor Extensions as a Formal DSL

Contract semantics are expressed via a deterministic extension model:

x-api-wrapper
x-api-wrapper-datatype
x-data-container
x-data-item
x-ignore-model

These are:

defined during projection
carried through OpenAPI
enforced during generation

🧪 Samples Decoupled from Runtime

Samples are moved to /samples and act as:

external consumers validating the platform

This separates platform logic from usage examples.

📘 Documentation Realignment

Docs are restructured around a contract lifecycle model:

problem → solution → proof → usage
clear server vs client responsibilities
projection vs authority distinction
mental model: thin adapters, not models

🎯 Outcome

Release 0.8.1 establishes the platform foundation:

platform is consumable via Maven Central
contract is defined once and reused everywhere
OpenAPI is a deterministic projection (not authority)
clients reconstruct contract shape instead of redefining it
build pipelines are predictable and maintainable

🔐 Compatibility

No breaking changes to:

response envelope semantics
OpenAPI schema meaning
runtime behavior

Changes are architectural and structural.

🧭 Direction

The platform now follows a strict principle:

define semantic contracts once — project, reconstruct, and consume them without reinterpretation

Everything else is infrastructure.

🚀 Looking Ahead

Next iterations will focus on:

expanding reusable contract tooling
validating multi-service adoption
preparing for 1.0.0 stabilization

The direction remains unchanged:

contract integrity, deterministic pipelines, and dependency-driven adoption.

v0.7.9 — Deterministic Client Generation & OpenAPI Template Governance

2026-03-25T14:48:21Z

Release 0.7.9 focuses on making generics‑aware client generation upgrade‑safe, deterministic, and operationally maintainable.

While earlier versions demonstrated the architectural pattern and stabilized runtime contract behavior, this release delivers a key engineering improvement:

Automated, fail‑fast governance of upstream OpenAPI Generator template changes.

The result is a significantly more robust client build pipeline that removes manual template maintenance risks and improves long‑term evolution safety.

No breaking changes were introduced to response envelope semantics or canonical contract usage.

✨ Highlights

⚙️ Fail‑Fast Governed OpenAPI Template Patching

Client generation now applies a deterministic build‑time patch to the upstream model.mustache template using Maven Antrun.

This replaces the previous approach where modified templates had to be:

manually copied
locally maintained
periodically re‑aligned with upstream generator changes

The new mechanism:

automatically extracts the upstream template during build
applies a controlled semantic patch targeting wrapper rendering
verifies the patch signature
fails the build immediately if upstream template structure changes

This establishes a safer upgrade path for OpenAPI Generator versions while preserving the generics‑aware wrapper model.

🧩 Simplified Generics Wrapper Rendering Strategy

Wrapper generation logic has been streamlined to reduce template surface area and eliminate redundant overlay complexity.

The client build now:

intercepts only the model rendering branch relevant to canonical response envelopes
keeps local template overlays minimal and declarative
preserves thin inheritance‑based wrappers bound to the shared api‑contract

This reduces maintenance burden and improves architectural clarity.

🔁 Deterministic Client Build Pipeline

The effective template generation process has been redesigned for reproducibility and developer ergonomics.

Key improvements include:

removal of unused upstream template copying stages
clearer separation between upstream extraction and local semantic governance
stable effective template directory structure
reduced risk of silent drift across generator upgrades

Client regeneration behaviour is now more predictable and observable.

🚀 Platform Stack Alignment

This release also aligns the example client module with updated platform components:

Spring Boot 3.5.12
OpenAPI Generator 7.21.0

These upgrades are incorporated within the new governed template pipeline to ensure compatibility and forward evolution safety.

📘 Architecture Documentation Refinement

Documentation has been restructured to better communicate the project as a contract lifecycle reference architecture.

Updates include:

clearer explanation of server vs client lifecycle responsibilities
explicit scoping of supported generic response shapes
improved conceptual flow across README and adoption guides

These changes improve onboarding clarity without affecting runtime behaviour.

🎯 Outcome

Release 0.7.9 represents an important engineering maturity milestone:

generics‑aware client generation becomes upgrade‑safe by design
manual template maintenance is eliminated
build failures surface upstream generator incompatibilities early
contract‑driven integration patterns become easier to operationalize

This strengthens the project’s long‑term goal:

stable response contracts, deterministic client regeneration, and architecture‑aware API integration boundaries for Spring ecosystems.

🧭 Looking Ahead

With governed template evolution now in place, future iterations are expected to focus on:

further modularization of reusable contract tooling
broader validation of the lifecycle pattern in multi‑service scenarios
incremental preparation for structural evolution in the upcoming 0.8.x line

The architectural direction remains consistent:

publish semantic contracts once — interpret and consume them safely across system boundaries.