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.

0.7.2: Client Generator Cleanup & .openapi-generator-ignore Support

Highlights

🧹 Generator Cleanup & Build Hygiene

• Added .openapi-generator-ignore to skip redundant generated DTOs:
  • ServiceResponse.java, ServiceResponseVoid.java, Meta.java, Sort.java, Page*.java
• These models now exist in the shared common package — avoiding regeneration and import conflicts.
• Added Spotless Maven plugin to clean unused imports in generated sources.
• Ensured generated code remains minimal and conflict-free during repeated client builds.

---

🧩 Client-Side Adoption Docs

• Updated client-side build setup guides:
  • Explicit plugin order (dependency → resources → generator → build-helper → spotless)
  • Version alignment for all build plugins.
  • Added documentation for .openapi-generator-ignore cleanup strategy.
• Improved internal consistency across customer-service-client and global docs/adoption.

---

🔧 Repository Alignment

• Updated customer-service-client README for final generator structure.
• Synced references across all docs for better cross-navigation.
• Prepared repository for v0.7.2 release baseline.

---

Next Steps

• Keep long-term plan open for future artifact publishing (no immediate release planned):
  • io.github.bsayli:openapi-generics-autoreg
  • io.github.bsayli:openapi-generics-templates

✅ Release focus: Client generator cleanup, redundant DTO exclusion, and consistent client-side build documentation.

0.7.1: Docs Overhaul & Client Error Handling

Highlights

⚙️ Core Enhancements

• Improved client-side error handling — all non-2xx responses now raise ClientProblemException.
• Added safe deserialization via ProblemDetailSupport.extract(...) with consistent fallbacks.
• Guaranteed non-null ProblemDetail even for empty or malformed responses.
• Updated documentation and examples to RFC 9457 — Problem Details for HTTP APIs, superseding RFC 7807.

---

📘 Documentation & Guides

• Rewrote all README.md for clarity and precision.
• Corrected Problem & Motivation examples to reflect actual OpenAPI output.
• Standardized terminology and links to RFC 9457 specification.

---

Next Steps

• Keep long-term plan open for future artifact publishing (no immediate release planned):
  • io.github.bsayli:openapi-generics-autoreg
  • io.github.bsayli:openapi-generics-templates

---

✅ Release focus: Documentation overhaul & client error handling improvements for version 0.7.1.

v0.7.0 – RFC 9457 & Nested Generics Support

Highlights

⚙️ Core Enhancements

• Introduced RFC 9457-compliant error handling (application/problem+json → ProblemDetail).

• Implemented dynamic nested generics support for ServiceResponse<Page<T>> and similar envelopes.

• Added vendor extensions:

  • x-api-wrapper (existing)
  • x-data-container and x-data-item for introspection of nested containers.

• Introduced generic Page schema for scalable list endpoints.

• Unified OpenAPI schema enrichment logic under AutoWrapperSchemaCustomizer, dynamically detecting all wrapper variations.

• Configurable via new properties:

  app:
    openapi:
      wrapper:
        class-extra-annotation: "@com.fasterxml.jackson.annotation.JsonIgnoreProperties(ignoreUnknown = true)"
        generic-containers:
          - Page

---

🧠 OpenAPI & Springdoc Integration

• Enhanced schema registration with dynamic detection of all ServiceResponse<T> and ServiceResponse<Page<T>> return types.
• Extended vendor metadata for better client template generation.
• Simplified controller setup — no manual schema definitions needed.

---

📘 Documentation & Guides

• Complete rewrite of all adoption guides (Server-Side, Client-Side, Build Setup).
• Clear examples showing both single and paged responses (ServiceClientResponse<T> and ServiceClientResponse<Page<T>>).
• Integrated ProblemDetail error model into all docs and examples.
• Added official RFC 9457 reference link
• Improved readability for GitHub Pages on both desktop and mobile.

---

🌐 GitHub Pages & Repository Updates

• Reorganized titles and navigation for cleaner layout (shorter page titles).
• Verified all code snippets for syntax and formatting consistency.
• README now highlights the { data, meta } envelope and nested generic architecture.
• Minor cleanup and alignment of module structures (customer-service, customer-service-client).

---

Why it matters

This release marks a major architectural milestone —
moving from static templates to a fully dynamic, generics-aware schema system with production-grade error handling.

Developers now get:

• Clean, type-safe client wrappers.
• Automatic OpenAPI schema generation for nested generics.
• Standardized RFC 9457 error responses across all services.
• A modern documentation site ready for onboarding and contribution.

---

Next Steps

• Keep long-term plan open for future artifact publishing (no immediate release planned):
  • io.github.bsayli:openapi-generics-autoreg
  • io.github.bsayli:openapi-generics-templates

---

✅ Release focus: RFC 9457 compliance, dynamic nested generics, pagination-aware wrappers, and full documentation alignment for version 0.7.0.

v0.6.8 – Docs Overhaul (GitHub Pages, Mustache, README)

Highlights

📘 Documentation & Adoption Guides

• Refined Mustache template snippet (correct imports, clarified optional x-class-extra-annotation block).
• Fixed formatting in OpenAPI Endpoints section (resolved oversized font issue).
• Documented OpenAPI spec location in customer-service-client (src/main/resources/customer-api-docs.yaml).
• Improved customer-service and customer-service-client READMEs with clarified examples and notes.

🌐 GitHub Pages

• Rebuilt Home page with a clear Problem → Solution → Benefits narrative.
• Added Quick Start and References & Links sections for easier onboarding.
• Improved rendering of code blocks, callouts, and diagrams for better readability.

🧹 Repo Cleanup

• Removed accidental .iml files from version control.
• Synced all module POMs to version 0.6.8 for consistency.

---

Why it matters

This release delivers a comprehensive documentation overhaul:

• GitHub Pages now presents a coherent story from problem to solution.
• Mustache usage and wrapper generation are explained cleanly and consistently.
• READMEs and adoption guides are aligned, making onboarding simpler for new users.
• Repository is cleaner and free from IDE artifacts.

---

Next Steps

• Prepare next milestone for publishing artifacts:
  • io.github.bsayli:openapi-generics-autoreg
  • io.github.bsayli:openapi-generics-templates

---

✅ Release focus: Documentation overhaul (GitHub Pages, Mustache, READMEs), repo cleanup, and version bump to 0.6.8.

v0.6.7 – Documentation Fixes, GitHub Pages

Highlights

📘 Documentation & Adoption Guides

• Fixed broken links in server module README (adapter/annotations references).
• Corrected formatting of Architecture at a Glance diagram for better rendering (esp. on mobile).
• Added missing Maven Properties snippet in client-side-adoption-pom.md for clarity.
• Improved Adoption Guides navigation in GitHub Pages (docs/).
• Cleaned up duplication in sidebar menus.

🌐 GitHub Pages

• Introduced project site via GitHub Pages:
  • bsayli.github.io/spring-boot-openapi-generics-clients
• Navigation sidebar now shows:
  • Home
  • Adoption Guides
    • Server-Side Adoption
    • Client-Side Adoption

🔧 Build & Version Sync

• Synced POM properties and plugin versions with current repo state.
• Fixed drift where module version remained at 0.6.5 after the 0.6.6 release — now aligned at 0.6.7.

---

Why it matters

This release strengthens the documentation and onboarding experience:

• GitHub Pages now provides a clean navigation experience for adoption guides.
• Server module README and guides are accurate, with fixed links and diagrams.
• POM versions are consistent across the repo.

---

Next Steps

• Prepare for artifact packaging:
  • io.github.bsayli:openapi-generics-autoreg (server-side schema auto-registration).
  • io.github.bsayli:openapi-generics-templates (client-side mustache overlays).
• Gather early feedback from teams using the docs via GitHub Pages.

---

✅ Release focus: Documentation polish, client and server-side documentation fixes, GitHub Pages availability, and POM sync.

v0.6.6 – Adoption Guides & Documentation Enhancements

Refinement over v0.6.5 with a strong focus on documentation and adoption guidance, enabling teams to integrate the generics-aware client pattern seamlessly into their own projects.

---

Highlights

📘 New Adoption Guides:

• Added docs/adoption/server-side-adoption.md — step-by-step guide to enabling wrapper schema registration in your microservice.
• Added docs/adoption/client-side-adoption.md — instructions to generate clients with generics-aware wrappers using Mustache overlays.
• Both guides include copy-paste ready snippets (Java + Maven + Mustache templates).

📄 Root README Updates:

• Added 📘 Adoption Guides section with direct links to server-side and client-side docs.
• Expanded Table of Contents for easier navigation.
• Improved clarity on how to reproduce the client build locally (mvn clean install) and inspect generated wrappers.

---

Why it matters

• Lowers the barrier for teams adopting generics-aware OpenAPI clients.
• Provides a clear reference for server-side producers and client-side consumers alike.
• Ensures documentation stays actionable and aligned with the evolving codebase.

---

Next Steps

• Prepare groundwork for packaging into standalone artifacts:
  • io.github.bsayli:openapi-generics-autoreg (server-side)
  • io.github.bsayli:openapi-generics-templates (client-side)

➡️ This release emphasizes ease of adoption and sets the stage for broader community usage.

v0.6.5 – OpenAPI Generator 7.16.0 & Template Enhancements

Refinement over v0.6.4 with upgraded OpenAPI Generator and smarter template overlays, enabling optional class annotations and cleaner wrapper generation.

---

Highlights

🔧 Core:

• Upgraded OpenAPI Generator → 7.16.0.
• Refined Mustache overlays (api_wrapper.mustache, model.mustache) to align with upstream changes.
• Introduced commonPackage usage for cleaner base reference across wrappers.

⚙️ Optional Enhancements:

• Added support for x-class-extra-annotation vendor extension → lets you attach annotations (e.g. Jackson, Lombok) directly on generated wrapper classes.
• Still optional — by default wrappers remain minimal (ServiceClientResponse<T>).

📦 customer-service:

• AutoWrapperSchemaCustomizer updated to propagate class-extra-annotation property.
• Optional config via application.yml (app.openapi.wrapper.class-extra-annotation).

---

Why it matters

• Keeps project up-to-date with the latest OpenAPI Generator while maintaining overlay compatibility.
• Provides teams an optional hook to enrich generated wrappers with annotations without custom forking.
• Strengthens the overall flexibility of the generics-aware client generation approach.

---

Next Steps

The long-term goal remains extraction into standalone artifacts:

• io.github.bsayli:openapi-generics-autoreg → server-side: auto-registers wrapper schemas.
• io.github.bsayli:openapi-generics-templates → client-side: generics-aware wrappers via Mustache overlays.

➡️ This will enable drop-in generics support across projects with zero boilerplate.

v0.6.4 – Docs overhaul & Docker fixes

Refinement over v0.6.3 with clearer documentation and working containerization across all modules.

---

Highlights

• 📖 Docs:

  • Rewrote root README with purpose, Compatibility Matrix, Quick Start, end-to-end generics flow, and clean ToC.
  • Expanded customer-service/README with CRUD endpoints, sample payloads, OpenAPI endpoints, Docker run instructions, and testing notes.
  • Strengthened customer-service-client/README with “Not a Published Library” disclaimer, scope & non-goals, TL;DR generation steps, adapter usage, Mustache overlay details, and troubleshooting guidance.

• 🐳 Docker:

  • Fixed Dockerfile so the service builds and runs successfully.
  • Added .dockerignore to trim build context (target/, .git, IDE files, etc.), improving build performance and reproducibility.

---

Why it matters

• Ensures new contributors can understand the project in minutes via polished docs.
• Provides a working container build out of the box, essential for demoing or running the service in different environments.
• Keeps the repo professional, clean, and easy to adopt by others.

---

Next Steps

The next evolution remains the extraction of auto schema registration and generics-aware templates into standalone modules, so any project using ServiceResponse<T> can enable this with a simple dependency:

• io.github.bsayli:openapi-generics-autoreg → server-side: auto-registers wrapper schemas in OpenAPI spec.
• io.github.bsayli:openapi-generics-templates → client-side: plugs into OpenAPI Generator for thin, type-safe wrappers.

➡️ This will make generics-aware OpenAPI support drop-in simple for any team, without copying templates or customizers.

v0.6.3 – Expanded tests, JaCoCo & Codecov integration

Refinement over v0.6.2 with stronger testing, reporting, and CI improvements across both modules: customer-service and customer-service-client.

Highlights
• 🐞 Fix: corrected incorrect package reference in CustomerControllerAdvice.
• ✅ Added missing integration tests for CustomerController (covering success, validation, type mismatch, not found, generic errors).
• 🧪 Strengthened coverage with unit & integration tests across service and client adapters.
• 📊 Introduced JaCoCo setup for combined unit/integration test reporting.
• 🔗 Integrated Codecov reporting into the CI workflow for PR visibility.

Why it matters
• Improves reliability by testing both happy-path and failure scenarios.
• Ensures API contract correctness (status codes, Location headers, error payloads).
• Provides visibility into coverage trends via Codecov, helping prioritize further testing.

Next Steps
The next natural step is to extract the auto schema registration and generics-aware templates into standalone modules. This will allow any project using ServiceResponse to enable the same behavior just by adding a dependency:
• io.github.bsayli:openapi-generics-autoreg → server-side: automatically registers wrapper schemas in the OpenAPI spec.
• io.github.bsayli:openapi-generics-templates → client-side: plugs into OpenAPI Generator for thin, type-safe wrappers.

This way, teams can adopt generics-aware OpenAPI support with a single Maven/Gradle line, without copying templates or customizers.