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.

v0.7.8 — Error Handling Stabilization & ProblemDetail Contract Alignment

Release 0.7.8 focuses on stabilizing end‑to‑end error handling behavior and aligning both server‑side runtime behavior and generated client integrations with the canonical Spring ProblemDetail‑based API contract.

While v0.7.7 established the shared api-contract module as a reusable architectural artifact, this release concentrates on operational correctness, contract consistency, and integration reliability across real request/response execution paths.

No breaking changes were introduced to existing response envelope semantics.

---

✨ Highlights

🛠 Unified Server‑Side Request Error Handling

Multiple partially overlapping request exception handlers have been replaced with a single deterministic ApiRequestExceptionHandler implementation.

This ensures consistent RFC‑9457 compliant problem responses for:

• validation failures
• malformed request bodies
• type mismatches
• missing parameters / headers
• unsupported HTTP methods
• resource not found scenarios
• generic internal server errors

The new structure improves maintainability and eliminates previously inconsistent response mappings.

---

📡 Spring ProblemDetail as the Single Error Contract

Client‑side error decoding is now fully aligned with Spring’s native ProblemDetail model, replacing earlier custom and generated representations.

This establishes a clear architectural direction:

• server publishes canonical ProblemDetail responses
• generated clients consume the same structure without DTO duplication
• error extensions remain contract‑driven via api-contract

The result is a more predictable cross‑service error propagation model.

---

🧩 Hardened Client Fallback Error Mapping

Generated client support layers now provide robust fallback problem construction for upstream edge cases such as:

• non‑JSON error responses
• unparsable problem payloads
• empty error bodies
• missing or unreadable HTTP status information

Fallback problem URN namespaces were corrected to use the service‑specific client identity (customer-service-client) to avoid misleading generic identifiers.

---

🧱 OpenAPI Contract Publication Simplification

The previous approach of injecting global error schemas via a custom OpenAPI response customizer has been removed.

This change:

• avoids schema drift between runtime behavior and published specification
• keeps the server contract closer to Spring native semantics
• simplifies long‑term evolution of generator‑aware response envelopes

Supporting OpenAPI customization components were refined and documented to clarify their responsibility boundaries.

---

📦 Client Package Structure Realignment

Generated client package naming has been adjusted from generic openapi.client conventions to service‑scoped package structures.

This improves:

• multi‑service client coexistence
• dependency readability
• long‑term modular extraction potential

---

🧪 Expanded Integration Test Coverage

Controller‑level integration tests were significantly extended to validate:

• full success envelope flows
• detailed validation error scenarios
• malformed JSON handling
• type mismatch diagnostics
• not‑found and fallback messaging
• pagination metadata consistency
• HTTP method constraint enforcement

This strengthens confidence in both runtime contract guarantees and generated client expectations.

---

🎯 Outcome

Release 0.7.8 improves the project’s architectural integrity by ensuring that:

• runtime error behavior is deterministic and contract‑aligned
• generated clients decode errors using the same canonical model
• OpenAPI publication remains consistent with actual execution semantics
• service‑scoped client packaging supports ecosystem scalability

The release represents a stabilization milestone focused on correctness rather than feature expansion.

---

🧭 Looking Ahead

With error handling semantics now clarified and aligned, upcoming iterations are expected to focus on:

• deeper modular separation between generator tooling and reusable runtime components
• continued refinement of contract‑aware OpenAPI customization strategies
• incremental preparation toward the structural evolution planned for the 0.8.x line

The long‑term direction remains unchanged:

stable contracts, predictable client generation, and architecture‑aware API integration patterns for Spring Boot ecosystems.

v0.7.7 — Canonical api-contract published to Maven Central

Release 0.7.7 introduces a major architectural milestone for the project by formally publishing the api-contract module to Maven Central and positioning it as the canonical shared response contract across the ecosystem.

While v0.7.6 focused on framework alignment, schema stabilization and dependency security updates, this release focuses on contract extraction, documentation maturity and ecosystem modularization.

No breaking changes were introduced to existing response envelope semantics.

---

✨ Highlights

📦 Canonical api-contract Published to Maven Central

The api-contract module is now available as a public Maven Central dependency.

This establishes a single authoritative response contract that can be reused across:

• backend services
• generated API clients
• integration adapters
• consumer applications

The goal is to eliminate duplicated response DTO hierarchies and ensure deterministic contract reuse across service boundaries.

Example dependency:

<dependency>
  <groupId>io.github.bsayli</groupId>
  <artifactId>api-contract</artifactId>
  <version>0.7.7</version>
</dependency>

This marks the first release where the response model becomes a stand‑alone architectural artifact rather than an internal module.

---

🧠 Contract Positioning & Documentation Maturity

Extensive Javadoc coverage has been added across core contract types, including:

• ServiceResponse
• pagination primitives
• sorting descriptors
• RFC 9457 extension structures

This improves IDE discoverability and clarifies intended usage semantics for downstream adopters.

The documentation now explicitly communicates:

• envelope ownership model
• additive evolution expectations
• generator‑safe nesting guarantees
• framework neutrality boundaries

---

📄 README Structural Refinement

The api-contract README has been significantly refined to better express:

• architectural intent
• explicit non‑goals of the library
• ecosystem usage scenarios
• version alignment recommendations

The module is now positioned as a long‑lived shared contract component designed to evolve predictably and remain tooling‑agnostic.

---

🔧 Ecosystem Alignment

All dependent modules within the repository have been updated to consume api-contract 0.7.7.

This ensures:

• consistent response envelope semantics
• synchronized contract versioning across server and generated clients
• cleaner dependency boundaries between architectural layers

The release also prepares the repository for future modular extraction work planned for the 0.8.x line.

---

🎯 Outcome

v0.7.7 establishes a clearer architectural direction for the project:

• response contracts are now reusable Maven artifacts
• documentation maturity supports external adoption
• contract ownership is centralized and explicit
• ecosystem modules are aligned on a shared baseline

This release strengthens the foundation for deterministic API design and generator‑friendly client ecosystems.

---

🧭 Looking Ahead

With the contract baseline now published and stabilized, upcoming iterations will focus on:

• deeper modular decomposition of reusable building blocks
• clearer separation between runtime infrastructure and contract artifacts
• incremental evolution toward a more composable architecture toolkit

The long‑term objective remains unchanged:

stable contracts, predictable generation workflows, and architecture‑aware API development for Spring Boot ecosystems.

v0.7.6 — Ecosystem Alignment, Schema Stabilization & Security Updates

Release 0.7.6 focuses on ecosystem alignment, OpenAPI schema stabilization, and dependency security updates.

While v0.7.5 concentrated on runtime hardening and RFC 9457 correctness, this release ensures the project stays aligned with the latest Spring ecosystem versions while eliminating remaining OpenAPI schema warnings and dependency security alerts.

No public API contracts or envelope semantics have changed.

---

✨ Highlights

⬆️ Framework & Tooling Alignment

Core framework and tooling versions have been updated to stay aligned with the current Spring ecosystem.

Updates include:

• Spring Boot → 3.5.11
• Springdoc OpenAPI → 2.8.16
• OpenAPI Generator → 7.20.0

These upgrades improve compatibility with the current Spring stack and ensure continued stability of OpenAPI generation and documentation.

---

🧩 OpenAPI Schema Stabilization

The server OpenAPI configuration now explicitly defines the schemas used for RFC 9457 responses.

A dedicated OpenAPI customizer ensures deterministic schema registration for:

• ProblemDetail
• ProblemExtensions
• ErrorItem

This eliminates schema resolution warnings previously emitted by Springdoc and guarantees stable schema references in generated OpenAPI documents.

Key improvements:

• Explicit schema definitions added to OpenAPI components
• Deterministic $ref usage for RFC 9457 structures
• Removal of schema generation warnings during documentation generation

Outcome:
OpenAPI output is now fully deterministic and warning‑free, ensuring stable client generation.

---

🔐 Jackson Security Update

Security scanners reported a vulnerability affecting the Jackson version pulled via the default dependency chain.

To address this:

• Jackson BOM overridden → 2.21.1

This ensures all Jackson modules (core, annotations, databind) resolve to a secure version while maintaining compatibility with the Spring Boot runtime environment.

---

🧪 Client Module Cleanup

The customer-service-client module received several small refinements:

• Logging dependencies limited to test scope where appropriate
• Dependency graph simplified
• Cleaner runtime classpath for client consumers

These changes reduce noise and improve dependency hygiene for downstream projects.

---

📄 OpenAPI Regeneration

The OpenAPI specification (api-docs.yml) was regenerated after the schema stabilization work.

Generated artifacts now:

• reference explicit ProblemDetail schemas
• avoid ambiguous schema inference
• produce deterministic client code

This improves reproducibility for generated clients across environments.

---

🎯 Outcome

v0.7.6 delivers a cleaner and more stable foundation for the project:

• Up‑to‑date Spring ecosystem alignment
• Deterministic OpenAPI schemas
• Removal of schema generation warnings
• Security‑patched Jackson dependency set
• Cleaner dependency structure for the generated client

No changes were made to the canonical response contract introduced in v0.7.4.

---

🧭 Looking Ahead

With the contract baseline stable and tooling aligned, the next iteration of the project will focus on structural modularization and reuse.

The planned 0.8.x line will extract reusable building blocks from the current repository into dedicated artifacts while preserving the existing architecture guarantees.

The goal remains the same:

deterministic contracts, predictable client generation, and architecture‑friendly API tooling for Spring Boot services.

v0.7.5 — Client Hardening, RFC 9457 Improvements & Docker Refinements

Release 0.7.5 is a stabilization and hardening release built on top of the canonical contract baseline introduced in v0.7.4.

While v0.7.4 established the shared api-contract and unified the repository around a single response envelope, v0.7.5 focuses on runtime robustness, error-handling correctness, Docker build quality, and documentation consistency — without changing the canonical contract surface.

---

✨ Highlights

⬆️ Framework & Tooling Alignment

• All modules bumped to 0.7.5
• Spring Boot → 3.5.10
• OpenAPI Generator → 7.19.0
• Dependency alignment across server and client modules

---

🧩 Client: RFC 9457 ProblemDetail Hardening

The customer-service-client now handles non‑2xx responses more defensively and deterministically.

Improvements include:

• Hardened ProblemDetail extraction

  • status read failures
  • body read failures
  • empty body handling
  • non‑JSON error responses
  • unparsable problem bodies

• Structured fallback ProblemDetail creation with explicit error codes

• Contextual extensions.errors for improved diagnostics

• Explicit client fallback type URNs under:

  urn:customer-service:problem:client-fallback-*
  

• Updated tests aligned with stricter, predictable behavior

Outcome:
The generated client behaves consistently even when upstream services return malformed or non‑RFC‑9457 compliant responses.

---

🌍 Server: Centralized Error Messages & i18n Readiness

Server-side error construction has been cleaned up and centralized.

• Error titles and details moved to messages.properties
• Introduced LocalizedMessageResolver
• Clear separation between message resolution and RFC 9457 problem assembly
• Consistent construction of errorCode and extensions.errors

Outcome:
Cleaner exception handlers, consistent error payloads, and a production-ready baseline for future localization.

---

🐳 Docker: Production-Grade Image Refinement

customer-service Docker build upgraded for correctness and cache efficiency:

• Multi-stage build
• Maven cache mount for faster rebuilds
• Spring Boot layered JAR extraction via layertools
• Non-root runtime user
• Improved filesystem ownership
• Better layer reuse across builds

Outcome:
More realistic production container behavior and faster incremental builds.

---

🧱 api-contract: Quality Refinements

• Minor refinements and cleanup in ServiceResponse<T>
• Improved null-handling and default behavior
• No changes to the canonical { data, meta } contract shape

The response envelope semantics introduced in v0.7.4 remain fully stable.

---

📚 Documentation & Structural Consistency

• READMEs refined and aligned with current architecture
• Adoption guides clarified
• Contract boundaries and Page-only nested generics rule documented more explicitly
• CI and publishing workflows adjusted for consistency

This release reduces ambiguity and adoption friction without expanding scope.

---

🎯 Outcome

• Canonical contract remains stable (v0.7.4 baseline preserved)
• Client error handling is significantly more robust
• Server error handling is cleaner and localization-ready
• Docker workflows reflect production expectations
• Documentation better represents architectural guarantees

This is a quality release: stronger defaults, fewer runtime surprises, and clearer boundaries — without expanding the public contract surface.

---

🧭 Next Steps — 0.8.x Modularization

With v0.7.4, the project reached a stable canonical contract baseline.
With v0.7.5, runtime robustness and structural clarity are reinforced.

The next minor line (0.8.x) will focus on clean modularization and reuse.

Planned 0.8.x Extraction

The remaining implementation will be separated into reusable artifacts while preserving architectural guarantees:

io.github.bsayli:openapi-generics-autoreg

Spring Boot / Springdoc integration:

• Wrapper registration via OpenApiCustomizer
• Deterministic schema naming for generics
• Explicit Page-only nested generics rule

io.github.bsayli:openapi-generics-templates

OpenAPI Generator overlays:

• Mustache templates for thin wrapper generation
• Client models extending the canonical contract
• Generator-safe, version-stable output

All artifacts will share the same 0.8.x version line and remain part of the project family.

0.8.x introduces no new concepts — only separation, reuse, and adoption readiness.

v0.7.5 consolidates the architecture.
v0.8.x will modularize it.

0.7.4 — Canonical API Contract & Spring Boot 3.5 Upgrade

This release introduces api-contract as a first-class module and aligns the entire repository around a single, shared canonical API contract.

The project is upgraded to Spring Boot 3.5.9, with all related dependencies and OpenAPI tooling aligned accordingly.

---

✨ Highlights

🧱 Canonical API Contract (api-contract)

• Single success envelope: ServiceResponse<T>
• Shared paging, metadata, and RFC 9457 extensions
• Framework-agnostic and reused by both server and client

🔗 Contract-Aligned Services

• customer-service consumes the shared contract directly
• customer-service-client generates thin wrappers only
• Page-only nested generics explicitly supported: ServiceResponse<Page<T>>

⬆️ Framework & Tooling Upgrades

• Spring Boot → 3.5.9
• Springdoc OpenAPI Starter → 2.8.15
• OpenAPI Generator → 7.18.0

🐳 Docker & CI Correctness

• Root aggregator reactor build
• Realistic Docker Compose workflow aligned with developer usage
• CI workflows updated to reflect the new module structure

📚 Documentation Overhaul

• Updated root README with a contract-driven focus
• New and updated adoption guides
• Updated diagrams and module-level documentation

---

🎯 Outcome

• Establishes one true API contract shared across server and client
• Eliminates response envelope duplication entirely
• Preserves type-safety for canonical response shapes, including ServiceResponse<Page<T>>
• Makes OpenAPI generation deterministic and generator-safe
• Turns the repository into a production-grade, contract-driven, generics-aware reference implementation

---

📌 Why this matters

The shift to a canonical api-contract was not a refactor, but a design decision:
owning the response envelope as a shared contract instead of letting generators invent it.

The full rationale and evolution of this approach is explained here:
We Made OpenAPI Generator Think in Generics

---

🧭 Next Steps

With v0.7.4, the project has reached a stable, canonical contract baseline.
The next minor line (0.8.x) will focus on clean modularization — separating responsibilities into reusable, independently consumable artifacts while preserving the same architectural guarantees.

Planned 0.8.x Modularization

With v0.7.4, io.github.bsayli:api-contract is already extracted and canonical.

The remaining implementation will be extracted into reusable artifacts to support broader adoption:

• io.github.bsayli:openapi-generics-autoreg
  Spring Boot / Springdoc integration:

  • Wrapper registration via OpenApiCustomizer
  • Deterministic schema naming for generics
  • Explicit Page-only nested generics rule

• io.github.bsayli:openapi-generics-templates
  OpenAPI Generator overlays:

  • Mustache templates for thin wrapper generation
  • Client models extending the canonical contract
  • Generator-safe, version-stable output

All artifacts will share the same 0.8.x version line and remain part of the
spring-boot-openapi-generics-clients project family.

0.8.x introduces no new concepts — only clean separation, reuse, and adoption readiness.

This release marks the point where the project stabilizes as a
contract-driven, generics-aware reference implementation
for OpenAPI client generation.

0.7.3: Framework Upgrades, Documentation & Diagram Refinements

🚀 Highlights

🧩 Framework Upgrades

• Upgraded to Spring Boot 3.4.11 and OpenAPI Generator 7.17.0
• Ensured compatibility across all modules and build configurations

📝 Documentation Enhancements

• Refined Architecture Overview section and fixed internal anchor links in README.md
• Updated badges and version references for full consistency (Java 21, Spring Boot 3.4.11, OpenAPI 7.17.0)
• Improved readability and section hierarchy throughout documentation

🧭 Diagram & Visual Updates

• Updated architectural-diagram.png for current framework versions
• Improved label contrast and alignment for clarity
• Ensured diagram reflects latest auto-wrapper registration and client generation flow

---

🔧 Internal Maintenance

• Updated codeql.yml with +security-and-quality query inclusion
• Minor markdown cleanup and link corrections across docs

---

✅ Release Focus

Minor framework and documentation updates ensuring stability, consistency, and clarity across the project.

---

🧭 Next Steps

With this release, the repository is now fully aligned and ready for modularization (0.8.x).
The upcoming version will introduce a clean separation into reusable artifacts to support broader adoption across microservices.

Planned 0.8.x Artifacts

• io.github.bsayli:response-envelope — unified { data, meta } model shared across all projects
• io.github.bsayli:openapi-generics-autoreg — automatic wrapper registrar (OpenApiCustomizer) for Spring Boot producers
• io.github.bsayli:openapi-generics-templates — Mustache overlay templates for generics-aware client generation

Each module will share the same version line (0.8.x) and belong to the unified project family under spring-boot-openapi-generics-clients.

---

Summary:

Upgraded core frameworks, improved documentation and visuals, and fixed internal anchors for seamless navigation and clarity.

✅ Next milestone: modularization and publish-ready artifacts for full end-to-end generics-aware integration.