chore(release): bump to v0.6.2 with improved API semantics, error handling, and client docs

### Core changes
- Upgraded **Spring Boot** from 3.4.9 → 3.4.10 (latest patch, bugfixes, stability).
- Standardized package root to `io.github.bsayli.customerservice` (cleaner structure, consistent with client package).
- `CustomerController#createCustomer` now returns **201 Created** with `Location` header (REST-compliant resource creation).
- Added `CustomerControllerAdvice` with detailed error responses:
  * validation errors mapped to field-level violations
  * type mismatch & unreadable requests logged clearly
  * unified `ServiceResponse<ErrorPayload>` contract for clients
- Updated `application.yaml` with explicit error inclusion settings (messages + violations, no stacktrace leakage).

### Documentation & tests
- Polished all **README.md** files for clarity:
  * simpler TL;DR sections
  * better examples for Spring wiring & adapter pattern
  * consistent terminology (removed “demo” wording)
- Expanded integration tests: full CRUD coverage + validation & error cases.
- Enhanced generated client docs: show strong typing, thin wrappers, adapter isolation.

### CI/CD
- GitHub Actions workflow updated:
  * uploads OpenAPI spec (YAML) as artifact
  * uploads generated client sources
  * ensures JDK 21 setup across all jobs

---

💡 **Why it matters:**
For client developers, v0.6.2 delivers a more predictable API contract (201 + Location, unified error payloads) and safer integration (no leaking stacktraces, consistent generics). Docs and CI improvements make it easier to adopt and trust the OpenAPI generics pattern in real projects.

Author: bsayli

.github/workflows/build.yml

@@ -5,6 +5,9 @@ on:
     branches: [ main ]
   pull_request:
 
+permissions:
+  contents: read
+
 jobs:
   build:
     runs-on: ubuntu-latest
@@ -24,4 +27,25 @@ jobs:
 
       - name: Build customer-service-client
         run: mvn -B clean verify
-        working-directory: customer-service-client
+        working-directory: customer-service-client
+
+      - name: List generated sources and spec
+        run: |
+          ls -R customer-service-client/target/generated-sources/openapi/src/gen/java || true
+          ls -l customer-service-client/target/classes/customer-api-docs.yaml || true
+
+      - name: Upload generated client sources
+        uses: actions/upload-artifact@v4
+        with:
+          name: generated-client-sources
+          path: customer-service-client/target/generated-sources/openapi/src/gen/java
+          if-no-files-found: warn
+          retention-days: 7
+
+      - name: Upload OpenAPI spec (YAML)
+        uses: actions/upload-artifact@v4
+        with:
+          name: customer-api-docs
+          path: customer-service-client/target/classes/customer-api-docs.yaml
+          if-no-files-found: warn
+          retention-days: 7

README.md

@@ -1,7 +1,7 @@
 # spring-boot-openapi-generics-clients
 
 [![Build](https://github.com/bsayli/spring-boot-openapi-generics-clients/actions/workflows/build.yml/badge.svg)](https://github.com/bsayli/spring-boot-openapi-generics-clients/actions/workflows/build.yml)
-[![Release](https://img.shields.io/github/v/release/bsayli/spring-boot-openapi-generics-clients?logo=github&label=release)](https://github.com/bsayli/spring-boot-openapi-generics-clients/releases/latest)
+[![Release](https://img.shields.io/github/v/release/bsayli/spring-boot-openapi-generics-clients?logo=github\&label=release)](https://github.com/bsayli/spring-boot-openapi-generics-clients/releases/latest)
 [![Java](https://img.shields.io/badge/Java-21-red?logo=openjdk)](https://openjdk.org/projects/jdk/21/)
 [![Spring Boot](https://img.shields.io/badge/Spring%20Boot-3.4.9-green?logo=springboot)](https://spring.io/projects/spring-boot)
 [![OpenAPI Generator](https://img.shields.io/badge/OpenAPI%20Generator-7.x-blue?logo=openapiinitiative)](https://openapi-generator.tech/)
@@ -14,7 +14,7 @@
 </p>
 
 **Type-safe client generation with Spring Boot & OpenAPI using generics.**
-This repository demonstrates how to teach OpenAPI Generator to work with generics in order to avoid boilerplate, reduce
+This repository demonstrates how to extend OpenAPI Generator to work with generics in order to avoid boilerplate, reduce
 duplicated wrappers, and keep client code clean.
 
 ---
@@ -43,9 +43,40 @@ This project shows how to:
 
 ---
 
+### How it works (under the hood)
+
+At generation time, the reference service **auto-registers** wrapper schemas in the OpenAPI doc:
+
+* A Spring `OpenApiCustomizer` scans controller return types and unwraps `ResponseEntity`, `CompletionStage`, Reactor (
+  `Mono`/`Flux`), etc. until it reaches `ServiceResponse<T>`.
+* For every discovered `T`, it adds a `ServiceResponse{T}` schema that composes the base envelope + the concrete `data`
+  type, and marks it with vendor extensions:
+
+    * `x-api-wrapper: true`
+    * `x-api-wrapper-datatype: <T>`
+
+The Java client then uses a tiny Mustache override to render **thin shells** for those marked schemas:
+
+```mustache
+// api_wrapper.mustache
+public class {{classname}}
+    extends io.github.bsayli.openapi.client.common.ServiceClientResponse<{{vendorExtensions.x-api-wrapper-datatype}}> {
+}
+```
+
+This is what turns e.g. `ServiceResponseCustomerCreateResponse` into:
+
+```java
+public class ServiceResponseCustomerCreateResponse
+        extends ServiceClientResponse<CustomerCreateResponse> {
+}
+```
+
+---
+
 ## ⚡ Quick Start
 
-Run the sample service:
+Run the reference service:
 
 ```bash
 cd customer-service
@@ -66,11 +97,11 @@ ServiceClientResponse<CustomerCreateResponse> response =
         customerControllerApi.createCustomer(request);
 ```
 
-### 🖼 Demo Swagger Screenshot
+### 🖼 Swagger Screenshot
 
 Here’s what the `create customer` endpoint looks like in Swagger UI after running the service:
 
-![Customer create demo](docs/images/swagger-customer-create.png)
+![Customer create example](docs/images/swagger-customer-create.png)
 
 ### 🖼 Generated Client Wrapper
 
@@ -83,6 +114,18 @@ Comparison of how OpenAPI Generator outputs looked **before** vs **after** addin
 **After (thin generic wrapper):**
 
 ![Generated client (after)](docs/images/generated-client-wrapper-after.png)
+
+---
+
+## ✅ Verify in 60 Seconds
+
+1. Clone this repo
+2. Run `mvn clean install -q`
+3. Open `customer-service-client/target/generated-sources/...`
+4. See the generated wrappers → they now extend a **generic base class** instead of duplicating fields.
+
+You don’t need to write a single line of code — the generator does the work.
+
 ---
 
 ## 🛠 Tech Stack & Features
@@ -120,23 +163,24 @@ spring-boot-openapi-generics-clients/
 
 ### ✨ Usage Example: Adapter Interface
 
-Sometimes you don’t want to expose all the thin wrappers directly.  
+Sometimes you don’t want to expose all the thin wrappers directly.
 A simple adapter interface can consolidate them into clean, type-safe methods:
 
 ```java
 public interface CustomerClientAdapter {
-   ServiceClientResponse<CustomerCreateResponse> createCustomer(CustomerCreateRequest request);
+    ServiceClientResponse<CustomerCreateResponse> createCustomer(CustomerCreateRequest request);
 
-   ServiceClientResponse<CustomerDto> getCustomer(Integer customerId);
+    ServiceClientResponse<CustomerDto> getCustomer(Integer customerId);
 
-   ServiceClientResponse<CustomerListResponse> getCustomers();
+    ServiceClientResponse<CustomerListResponse> getCustomers();
 
-   ServiceClientResponse<CustomerUpdateResponse> updateCustomer(
-           Integer customerId, CustomerUpdateRequest request);
+    ServiceClientResponse<CustomerUpdateResponse> updateCustomer(
+            Integer customerId, CustomerUpdateRequest request);
 
-   ServiceClientResponse<CustomerDeleteResponse> deleteCustomer(Integer customerId);
+    ServiceClientResponse<CustomerDeleteResponse> deleteCustomer(Integer customerId);
 }
 ```
+
 ---
 
 ## 🔍 Why This Matters
@@ -163,7 +207,7 @@ This pattern is useful when:
 
 ## 🔧 How to Run
 
-1. **Start the sample service**
+1. **Start the reference service**
 
    ```bash
    cd customer-service
@@ -186,6 +230,24 @@ This pattern is useful when:
 
 ---
 
+## 👤 Who Should Use This?
+
+* Backend developers maintaining multiple microservices
+* API platform teams standardizing response envelopes
+* Teams already invested in OpenAPI Generator looking to reduce boilerplate
+
+---
+
+## ⚠️ Why Not Use It?
+
+This project may not be the right fit if:
+
+* Your APIs do **not** use a common response wrapper
+* You are fine with duplicated wrapper models
+* You don’t generate client code from OpenAPI specs
+
+---
+
 ## 📖 Related Article
 
 This repository is based on my article:

customer-service-client/README.md

@@ -1,13 +1,32 @@
 # customer-service-client
 
-Generated Java client for the demo **customer-service**, showcasing **type-safe generic responses** with OpenAPI + a
+Generated Java client for the **customer-service**, showcasing **type-safe generic responses** with OpenAPI + a
 custom Mustache template (wrapping payloads in a reusable `ServiceClientResponse<T>`).
 
 This module demonstrates how to evolve OpenAPI Generator with minimal customization to support generic response
 envelopes — avoiding duplicated wrappers and preserving strong typing.
 
 ---
 
+## 🔧 TL;DR: Generate in 1 minute
+
+```bash
+# 1) Start the customer service server (in another shell)
+cd customer-service && mvn -q spring-boot:run
+
+# 2) Pull the OpenAPI spec into the client module
+cd ../customer-service-client
+curl -s http://localhost:8084/customer-service/v3/api-docs.yaml \
+  -o src/main/resources/customer-api-docs.yaml
+
+# 3) Generate & compile the client
+mvn -q clean install
+```
+
+Generated sources → `target/generated-sources/openapi/src/gen/java`
+
+---
+
 ## ✅ What You Get
 
 * Generated code using **OpenAPI Generator** (`restclient` with Spring Framework `RestClient`).
@@ -42,11 +61,14 @@ curl -s http://localhost:8084/customer-service/v3/api-docs.yaml \
 mvn clean install
 ```
 
-Generated sources will be placed under:
+### What got generated?
 
-```
-target/generated-sources/openapi/src/gen/java
-```
+Look for these classes under `target/generated-sources/openapi/src/gen/java`:
+
+* `io.github.bsayli.openapi.client.generated.dto.ServiceResponseCustomerCreateResponse`
+* `...ServiceResponseCustomerUpdateResponse`, etc.
+
+Each is a **thin shell** extending `ServiceClientResponse<PayloadType>`.
 
 ---
 
@@ -108,6 +130,10 @@ public void createCustomer() {
 }
 ```
 
+> Tip — The return type is strongly typed: `ServiceClientResponse<CustomerCreateResponse>`.
+> You can safely navigate `resp.getData().getCustomer()` without casting.
+> Handle non-2xx via Spring exceptions (e.g., `HttpClientErrorException`) as usual.
+
 ---
 
 ### Option A.2 — Alternative with HttpClient5 (connection pooling)
@@ -161,7 +187,7 @@ public class CustomerApiClientConfig {
     @Bean
     ApiClient customerApiClient(RestClient customerRestClient,
                                 @Value("${customer.api.base-url}") String baseUrl) {
-        return new ApiClient(restClient).setBasePath(baseUrl);
+        return new ApiClient(customerRestClient).setBasePath(baseUrl);
     }
 
     @Bean
@@ -257,6 +283,20 @@ public class ServiceResponseCustomerCreateResponse
 
 Only this Mustache partial is customized. All other models use stock templates.
 
+### Template overlay (Mustache)
+
+This module overlays **two** tiny Mustache files on top of the stock Java generator:
+
+* `src/main/resources/openapi-templates/api_wrapper.mustache`
+* `src/main/resources/openapi-templates/model.mustache`
+
+At build time, the Maven `maven-dependency-plugin` unpacks the upstream templates and the
+`maven-resources-plugin` overlays the two local files. That’s what enables thin generic wrappers.
+
+**Disable templates (optional):**
+set `<templateDirectory>` to a non-existent path or comment the overlay steps in `pom.xml`
+to compare stock output vs generic wrappers.
+
 ---
 
 ## 🧪 Tests
@@ -277,14 +317,25 @@ It enqueues responses for **all CRUD operations** and asserts correct mapping in
 * Dependencies like `spring-web`, `spring-context`, `jackson-*`, `jakarta.*` are marked **provided**; your host app
   supplies them.
 * Generator options: Spring 6 `RestClient`, Jakarta EE, Jackson, Java 21.
-* OpenAPI spec path:
+* OpenAPI spec lives at: `src/main/resources/customer-api-docs.yaml`.
+  If you re-run the server and want an updated client, re-pull the spec:
 
-```
-src/main/resources/customer-api-docs.yaml
-```
+  ```bash
+  curl -s http://localhost:8084/customer-service/v3/api-docs.yaml \
+    -o src/main/resources/customer-api-docs.yaml
+  mvn -q clean install
+  ```
 
 ---
 
 ## 🛡 License
 
 This repository is licensed under **MIT** (root `LICENSE`). Submodules inherit the license.
+
+### Packaging note (optional)
+
+This module is **reference-oriented**. If you want to publish it as a reusable library later:
+
+* remove `provided` scopes and pin minimal runtime deps,
+* add a semantic version and release process (e.g., GitHub Release + `mvn deploy` to Maven Central),
+* keep the Mustache overlay in-repo for transparent builds.

customer-service-client/pom.xml

@@ -6,7 +6,7 @@
 
     <groupId>io.github.bsayli</groupId>
     <artifactId>customer-service-client</artifactId>
-    <version>0.6.1</version>
+    <version>0.6.2</version>
     <name>customer-service-client</name>
     <description>Generated client (RestClient) using generics-aware OpenAPI templates</description>
     <packaging>jar</packaging>
@@ -16,7 +16,7 @@
         <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
         <java.version>21</java.version>
 
-        <spring-boot.version>3.4.9</spring-boot.version>
+        <spring-boot.version>3.4.10</spring-boot.version>
         <openapi.generator.version>7.15.0</openapi.generator.version>
         <maven.compiler.plugin.version>3.13.0</maven.compiler.plugin.version>
         <build.helper.plugin.version>3.6.0</build.helper.plugin.version>