chore: bump to 0.4.0 and align service/client with generics-aware OpenAPI

- Bump versions to 0.4.0 in both customer-service and customer-service-client modules
- Update OpenApiConfig to inject version from pom.properties instead of hardcoding
- Remove VERSION constant from OpenApiConstants (cleaner centralization)
- Add app.openapi.base-url property support and wire into OpenAPI server section
- Introduce Apache HttpClient 5 configuration (connection pooling, timeouts) in customer-service-client
- Update CustomerApiClientConfig to use HttpClient5-backed RestClient
- Standardize response envelope classes: ServiceResponse<T> and ErrorDetail
- Clean up naming of generated wrappers (ServiceResponseCustomerXxxResponse)
- Improve integration tests using MockWebServer for CRUD endpoints
- Update README and docs (badges, social preview, before/after comparison images)
- General dependency alignment and cleanup of Maven properties

Author: barissayli

README.md

@@ -1,10 +1,11 @@
 # spring-boot-openapi-generics-clients
 
-![Build](https://github.com/bsayli/spring-boot-openapi-generics-clients/actions/workflows/build.yml/badge.svg)
-![Java](https://img.shields.io/badge/Java-21-red)
-![Spring Boot](https://img.shields.io/badge/Spring%20Boot-3.4-green)
-![OpenAPI](https://img.shields.io/badge/OpenAPI-Generator-blue)
-![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)
+[![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)
+[![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](https://img.shields.io/badge/OpenAPI-Generator-7.x-blue?logo=openapiinitiative)](https://openapi-generator.tech/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
 <p align="center">
   <img src="docs/images/social-preview.png" alt="Social preview" width="720"/>
@@ -20,9 +21,9 @@ duplicated wrappers, and keep client code clean.
 
 ## 🚀 Problem Statement
 
-Most backend teams standardize responses with a generic wrapper like `ApiResponse<T>`.
-However, **OpenAPI Generator does not natively support generics** — instead, it generates one wrapper per endpoint
-(duplicating fields like `status`, `message`, and `errors`).
+Most backend teams standardize responses with a generic wrapper like `ServiceResponse<T>`.
+However, **OpenAPI Generator does not natively support generics** — instead, it generates one wrapper per endpoint (
+duplicating fields like `status`, `message`, and `errors`).
 
 This creates:
 
@@ -61,8 +62,8 @@ mvn clean install
 Use the generated API:
 
 ```java
-ApiClientResponse<CustomerCreateResponse> response =
-    customerControllerApi.createCustomer(request);
+ServiceClientResponse<CustomerCreateResponse> response =
+        customerControllerApi.createCustomer(request);
 ```
 
 ### 🖼 Demo Swagger Screenshot
@@ -73,20 +74,26 @@ Here’s what the `create customer` endpoint looks like in Swagger UI after runn
 
 ### 🖼 Generated Client Wrapper
 
-And here’s the corresponding generated client class showing the generic wrapper:
+Comparison of how OpenAPI Generator outputs looked **before** vs **after** adding the generics-aware wrapper:
 
-![Generated client wrapper](docs/images/generated-client-wrapper.png)
+**Before (duplicated full model):**
 
+![Generated client (before)](docs/images/generated-client-wrapper-before.png)
+
+**After (thin generic wrapper):**
+
+![Generated client (after)](docs/images/generated-client-wrapper-after.png)
 ---
 
 ## 🛠 Tech Stack & Features
 
 * 🚀 **Java 21** — modern language features
-* 🍃 **Spring Boot 3.4** — microservice foundation
+* 🍃 **Spring Boot 3.4.9** — microservice foundation
 * 📖 **Springdoc OpenAPI** — API documentation
 * 🔧 **OpenAPI Generator 7.x** — client code generation
 * 🧩 **Custom Mustache templates** — generics-aware wrappers
 * 🧪 **JUnit 5 + MockWebServer** — integration testing
+* 🌐 **Apache HttpClient 5** — connection pooling & timeouts
 
 ---
 
@@ -103,7 +110,7 @@ spring-boot-openapi-generics-clients/
 
 ## 🧩 Key Features
 
-* ✅ **Generic base model**: `ApiClientResponse<T>`
+* ✅ **Generic base model**: `ServiceClientResponse<T>`
 * ✅ **Thin wrappers**: endpoint-specific shells extending the base
 * ✅ **Strong typing preserved**: `getData()` returns the exact payload type
 * ✅ **No duplicated fields** across wrappers
@@ -152,7 +159,7 @@ This pattern is useful when:
 3. **Use the generated API**
 
    ```java
-   ApiClientResponse<CustomerCreateResponse> response =
+   ServiceClientResponse<CustomerCreateResponse> response =
        customerControllerApi.createCustomer(request);
    ```
 

customer-service-client/README.md

@@ -1,7 +1,7 @@
 # customer-service-client
 
 Generated Java client for the demo **customer-service**, showcasing **type-safe generic responses** with OpenAPI + a
-custom Mustache template (wrapping payloads in a reusable `ApiClientResponse<T>`).
+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.
@@ -11,8 +11,8 @@ envelopes — avoiding duplicated wrappers and preserving strong typing.
 ## ✅ What You Get
 
 * Generated code using **OpenAPI Generator** (`restclient` with Spring Framework `RestClient`).
-* A reusable generic base: `io.github.bsayli.openapi.client.common.ApiClientResponse<T>`.
-* Thin wrappers per endpoint (e.g. `ApiResponseCustomerCreateResponse`, `ApiResponseCustomerUpdateResponse`).
+* A reusable generic base: `io.github.bsayli.openapi.client.common.ServiceClientResponse<T>`.
+* Thin wrappers per endpoint (e.g. `ServiceResponseCustomerCreateResponse`, `ServiceResponseCustomerUpdateResponse`).
 * Spring Boot configuration to auto-expose the client as beans.
 * Focused integration tests using **OkHttp MockWebServer** covering all CRUD endpoints.
 
@@ -57,28 +57,29 @@ target/generated-sources/openapi/src/gen/java/main
 Include this module as a dependency and configure the base URL:
 
 ```java
+
 @Configuration
 public class CustomerApiClientConfig {
 
-  @Bean
-  public RestClient customerRestClient(RestClient.Builder builder,
-                                       @Value("${customer.api.base-url}") String baseUrl) {
-    return builder.baseUrl(baseUrl).build();
-  }
-
-  @Bean
-  public io.github.bsayli.openapi.client.generated.invoker.ApiClient customerApiClient(
-      RestClient customerRestClient,
-      @Value("${customer.api.base-url}") String baseUrl) {
-    return new io.github.bsayli.openapi.client.generated.invoker.ApiClient(customerRestClient)
-        .setBasePath(baseUrl);
-  }
-
-  @Bean
-  public io.github.bsayli.openapi.client.generated.api.CustomerControllerApi customerControllerApi(
-      io.github.bsayli.openapi.client.generated.invoker.ApiClient apiClient) {
-    return new io.github.bsayli.openapi.client.generated.api.CustomerControllerApi(apiClient);
-  }
+    @Bean
+    public RestClient customerRestClient(RestClient.Builder builder,
+                                         @Value("${customer.api.base-url}") String baseUrl) {
+        return builder.baseUrl(baseUrl).build();
+    }
+
+    @Bean
+    public io.github.bsayli.openapi.client.generated.invoker.ApiClient customerApiClient(
+            RestClient customerRestClient,
+            @Value("${customer.api.base-url}") String baseUrl) {
+        return new io.github.bsayli.openapi.client.generated.invoker.ApiClient(customerRestClient)
+                .setBasePath(baseUrl);
+    }
+
+    @Bean
+    public io.github.bsayli.openapi.client.generated.api.CustomerControllerApi customerControllerApi(
+            io.github.bsayli.openapi.client.generated.invoker.ApiClient apiClient) {
+        return new io.github.bsayli.openapi.client.generated.api.CustomerControllerApi(apiClient);
+    }
 }
 ```
 
@@ -91,27 +92,93 @@ customer.api.base-url=http://localhost:8084/customer-service
 **Usage example:**
 
 ```java
+
 @Autowired
 private io.github.bsayli.openapi.client.generated.api.CustomerControllerApi customerApi;
 
 public void createCustomer() {
-  var req = new io.github.bsayli.openapi.client.generated.dto.CustomerCreateRequest()
-      .name("Jane Doe")
-      .email("[email protected]");
+    var req = new io.github.bsayli.openapi.client.generated.dto.CustomerCreateRequest()
+            .name("Jane Doe")
+            .email("[email protected]");
+
+    var resp = customerApi.createCustomer(req); // ServiceResponseCustomerCreateResponse
+
+    System.out.println(resp.getStatus());                       // 201
+    System.out.println(resp.getData().getCustomer().getName()); // "Jane Doe"
+}
+```
+
+---
+
+### Option A.2 — Alternative with HttpClient5 (connection pooling)
+
+If you want more control (connection pooling, timeouts, etc.), you can wire the client with **Apache HttpClient5**:
 
-  var resp = customerApi.createCustomer(req); // ApiResponseCustomerCreateResponse
+```java
+
+@Configuration
+public class CustomerApiClientConfig {
+
+    @Bean(destroyMethod = "close")
+    CloseableHttpClient customerHttpClient(
+            @Value("${customer.api.max-connections-total:64}") int maxTotal,
+            @Value("${customer.api.max-connections-per-route:16}") int maxPerRoute) {
+
+        var cm = PoolingHttpClientConnectionManagerBuilder.create()
+                .setMaxConnTotal(maxTotal)
+                .setMaxConnPerRoute(maxPerRoute)
+                .build();
+
+        return HttpClients.custom()
+                .setConnectionManager(cm)
+                .evictExpiredConnections()
+                .evictIdleConnections(org.apache.hc.core5.util.TimeValue.ofSeconds(30))
+                .setUserAgent("customer-service-client")
+                .disableAutomaticRetries()
+                .build();
+    }
+
+    @Bean
+    HttpComponentsClientHttpRequestFactory customerRequestFactory(
+            CloseableHttpClient customerHttpClient,
+            @Value("${customer.api.connect-timeout-seconds:10}") long connect,
+            @Value("${customer.api.connection-request-timeout-seconds:10}") long connReq,
+            @Value("${customer.api.read-timeout-seconds:15}") long read) {
+
+        var f = new HttpComponentsClientHttpRequestFactory(customerHttpClient);
+        f.setConnectTimeout(Duration.ofSeconds(connect));
+        f.setConnectionRequestTimeout(Duration.ofSeconds(connReq));
+        f.setReadTimeout(Duration.ofSeconds(read));
+        return f;
+    }
 
-  System.out.println(resp.getStatus());                      // 201
-  System.out.println(resp.getData().getCustomer().getName()); // "Jane Doe"
+    @Bean
+    RestClient customerRestClient(RestClient.Builder builder,
+                                  HttpComponentsClientHttpRequestFactory rf) {
+        return builder.requestFactory(rf).build();
+    }
+
+    @Bean
+    ApiClient customerApiClient(RestClient restClient,
+                                @Value("${customer.api.base-url}") String baseUrl) {
+        return new ApiClient(restClient).setBasePath(baseUrl);
+    }
+
+    @Bean
+    CustomerControllerApi customerControllerApi(ApiClient apiClient) {
+        return new CustomerControllerApi(apiClient);
+    }
 }
 ```
 
+---
+
 ### Option B — Manual Wiring (no Spring context)
 
 ```java
 var rest = RestClient.builder().baseUrl("http://localhost:8084/customer-service").build();
 var apiClient = new io.github.bsayli.openapi.client.generated.invoker.ApiClient(rest)
-    .setBasePath("http://localhost:8084/customer-service");
+        .setBasePath("http://localhost:8084/customer-service");
 var customerApi = new io.github.bsayli.openapi.client.generated.api.CustomerControllerApi(apiClient);
 ```
 
@@ -125,7 +192,7 @@ For larger applications, encapsulate the generated API in an adapter:
 package io.github.bsayli.openapi.client.adapter.impl;
 
 import io.github.bsayli.openapi.client.adapter.CustomerClientAdapter;
-import io.github.bsayli.openapi.client.common.ApiClientResponse;
+import io.github.bsayli.openapi.client.common.ServiceClientResponse;
 import io.github.bsayli.openapi.client.generated.api.CustomerControllerApi;
 import io.github.bsayli.openapi.client.generated.dto.*;
 import org.springframework.stereotype.Service;
@@ -140,27 +207,27 @@ public class CustomerClientAdapterImpl implements CustomerClientAdapter {
     }
 
     @Override
-    public ApiClientResponse<CustomerCreateResponse> createCustomer(CustomerCreateRequest request) {
+    public ServiceClientResponse<CustomerCreateResponse> createCustomer(CustomerCreateRequest request) {
         return customerControllerApi.createCustomer(request);
     }
 
     @Override
-    public ApiClientResponse<CustomerDto> getCustomer(Integer customerId) {
+    public ServiceClientResponse<CustomerDto> getCustomer(Integer customerId) {
         return customerControllerApi.getCustomer(customerId);
     }
 
     @Override
-    public ApiClientResponse<CustomerListResponse> getCustomers() {
+    public ServiceClientResponse<CustomerListResponse> getCustomers() {
         return customerControllerApi.getCustomers();
     }
 
     @Override
-    public ApiClientResponse<CustomerUpdateResponse> updateCustomer(Integer customerId, CustomerUpdateRequest request) {
+    public ServiceClientResponse<CustomerUpdateResponse> updateCustomer(Integer customerId, CustomerUpdateRequest request) {
         return customerControllerApi.updateCustomer(customerId, request);
     }
 
     @Override
-    public ApiClientResponse<CustomerDeleteResponse> deleteCustomer(Integer customerId) {
+    public ServiceClientResponse<CustomerDeleteResponse> deleteCustomer(Integer customerId) {
         return customerControllerApi.deleteCustomer(customerId);
     }
 }
@@ -170,7 +237,8 @@ This ensures:
 
 * Generated code stays isolated.
 * Business code depends only on the adapter interface.
-* Naming conventions are consistent with the service (createCustomer, getCustomer, getCustomers, updateCustomer, deleteCustomer).
+* Naming conventions are consistent with the service (createCustomer, getCustomer, getCustomers, updateCustomer,
+  deleteCustomer).
 
 ---
 
@@ -179,11 +247,11 @@ This ensures:
 The template at `src/main/resources/openapi-templates/api_wrapper.mustache` emits wrappers like:
 
 ```java
-import io.github.bsayli.openapi.client.common.ApiClientResponse;
+import io.github.bsayli.openapi.client.common.ServiceClientResponse;
 
-// e.g., ApiResponseCustomerCreateResponse
-public class ApiResponseCustomerCreateResponse
-        extends ApiClientResponse<CustomerCreateResponse> {
+// e.g., ServiceResponseCustomerCreateResponse
+public class ServiceResponseCustomerCreateResponse
+        extends ServiceClientResponse<CustomerCreateResponse> {
 }
 ```
 
@@ -199,13 +267,15 @@ Integration test with MockWebServer:
 mvn -q -DskipITs=false test
 ```
 
-It enqueues responses for **all CRUD operations** and asserts correct mapping into the respective wrappers (e.g. `ApiResponseCustomerCreateResponse`, `ApiResponseCustomerUpdateResponse`).
+It enqueues responses for **all CRUD operations** and asserts correct mapping into the respective wrappers (e.g.
+`ServiceResponseCustomerCreateResponse`, `ServiceResponseCustomerUpdateResponse`).
 
 ---
 
 ## 📚 Notes
 
-* Dependencies like `spring-web`, `spring-context`, `jackson-*`, `jakarta.*` are marked **provided**; your host app supplies them.
+* 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: