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

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

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

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

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

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

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

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

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

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

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.