docs: add adoption guides and update root README

barissayli · barissayli · commit c45dc49d12c8 · 2025-09-30T12:21:24.000-06:00
- Added server-side-adoption.md and client-side-adoption.md under docs/adoption
- Updated root README with links to adoption guides
- Extended Table of Contents for better navigation
diff --git a/README.md b/README.md
@@ -33,6 +33,7 @@ duplicated wrappers, and keep client code clean.
 - ✅ [Key Features](#-key-features)
 - ✨ [Usage Example](#-usage-example-adapter-interface)
 - 📦 [Related Modules](#-related-modules-quick-view)
+- 📘 [Adoption Guides](#-adoption-guides)
 
 ### 📦 Modules in this Repository
 
@@ -343,4 +344,14 @@ If you found this project useful, please consider giving it a star ⭐ on GitHub
 | Module                         | Description                                 | Docs                                        |
 |--------------------------------|---------------------------------------------|---------------------------------------------|
 | 🟢 **customer-service**        | Spring Boot sample API (producer)           | [README](customer-service/README.md)        |
-| 🔵 **customer-service-client** | Generated Java client with generics support | [README](customer-service-client/README.md) |
+| 🔵 **customer-service-client** | Generated Java client with generics support | [README](customer-service-client/README.md) |
+
+---
+
+## 📘 Adoption Guides
+
+Looking to integrate this approach into your own project?  
+See the detailed guides under [`docs/adoption`](docs/adoption):
+
+- [Server-Side Adoption](docs/adoption/server-side-adoption.md)
+- [Client-Side Adoption](docs/adoption/client-side-adoption.md)
diff --git a/docs/adoption/client-side-adoption.md b/docs/adoption/client-side-adoption.md
@@ -0,0 +1,203 @@
+# Client-Side Integration Guide
+
+This document describes how to integrate the **generics-aware OpenAPI client** into your own microservice project, based on the patterns demonstrated in the `customer-service-client` module.
+
+The purpose is to generate **type-safe clients** that extend a reusable generic base (`ServiceClientResponse<T>`) instead of duplicating response envelopes.
+
+---
+
+## 1) What You Get
+
+* Thin wrappers per endpoint (`ServiceResponseYourDto`), each extending `ServiceClientResponse<T>`.
+* Strong typing for `getData()` without boilerplate or casting.
+* A reusable adapter interface to keep generated code isolated.
+* Optional Spring Boot configuration to auto-wire the client beans.
+
+---
+
+## 2) Prerequisites
+
+* Java 21+
+* Maven 3.9+ (or Gradle 8+ if adapted)
+* Running service exposing `/v3/api-docs.yaml`
+
+---
+
+## 3) Steps to Generate
+
+1. **Pull the OpenAPI spec** from your service:
+
+   ```bash
+   curl -s http://localhost:8084/your-service/v3/api-docs.yaml \
+     -o src/main/resources/your-api-docs.yaml
+   ```
+
+2. **Run Maven build** in the client module:
+
+   ```bash
+   mvn clean install
+   ```
+
+3. **Inspect generated code**:
+
+    * `target/generated-sources/openapi/src/gen/java`
+    * Look for classes like `ServiceResponseYourDto` extending `ServiceClientResponse<YourDto>`
+
+---
+
+## 4) Core Classes to Copy
+
+Ensure you copy the following **shared classes** into your client project:
+
+**`common/ServiceClientResponse.java`**
+
+```java
+package <your.base>.openapi.client.common;
+
+import java.util.List;
+import java.util.Objects;
+
+public class ServiceClientResponse<T> {
+  private Integer status;
+  private String message;
+  private List<ClientErrorDetail> errors;
+  private T data;
+  // getters, setters, equals, hashCode, toString
+}
+```
+
+**`common/ClientErrorDetail.java`**
+
+```java
+package <your.base>.openapi.client.common;
+
+public record ClientErrorDetail(String errorCode, String message) {}
+```
+
+These are referenced by the Mustache templates and must exist in your client project.
+
+---
+
+## 5) Mustache Templates
+
+Place the following templates under:
+
+```
+src/main/resources/openapi-templates/
+```
+
+**`api_wrapper.mustache`**
+
+```mustache
+{{#vendorExtensions.x-class-extra-annotation}}
+{{{vendorExtensions.x-class-extra-annotation}}}
+{{/vendorExtensions.x-class-extra-annotation}}
+public class {{classname}}
+    extends {{commonPackage}}.ServiceClientResponse<{{vendorExtensions.x-api-wrapper-datatype}}> {
+}
+```
+
+**`model.mustache`** (partial overlay to delegate wrapper classes to `api_wrapper.mustache`).
+
+These ensure generated wrappers extend the generic base instead of duplicating fields.
+
+---
+
+## 6) Adapter Pattern
+
+Encapsulate generated APIs in an adapter interface:
+
+```java
+package <your.base>.openapi.client.adapter;
+
+import <your.base>.openapi.client.common.ServiceClientResponse;
+import <your.base>.openapi.client.generated.dto.*;
+
+public interface YourClientAdapter {
+  ServiceClientResponse<YourDto> getYourEntity(Integer id);
+  ServiceClientResponse<YourCreateResponse> createYourEntity(YourCreateRequest request);
+}
+```
+
+This shields your business code from generated artifacts and provides a stable contract.
+
+---
+
+## 7) Spring Boot Configuration (Optional)
+
+Example auto-wiring configuration:
+
+```java
+@Configuration
+public class YourApiClientConfig {
+
+  @Bean
+  RestClient yourRestClient(RestClient.Builder builder,
+                            @Value("${your.api.base-url}") String baseUrl) {
+    return builder.baseUrl(baseUrl).build();
+  }
+
+  @Bean
+  ApiClient yourApiClient(RestClient yourRestClient,
+                          @Value("${your.api.base-url}") String baseUrl) {
+    return new ApiClient(yourRestClient).setBasePath(baseUrl);
+  }
+
+  @Bean
+  YourControllerApi yourControllerApi(ApiClient apiClient) {
+    return new YourControllerApi(apiClient);
+  }
+}
+```
+
+**application.properties:**
+
+```properties
+your.api.base-url=http://localhost:8084/your-service
+```
+
+---
+
+## 8) Usage Example
+
+```java
+@Autowired
+private YourControllerApi yourApi;
+
+public void demo() {
+    var req = new YourCreateRequest().name("Alice");
+    var resp = yourApi.createYourEntity(req);
+    System.out.println(resp.getStatus());
+    System.out.println(resp.getData().getName());
+}
+```
+
+---
+
+## 9) Notes
+
+* Dependencies like `spring-web`, `jakarta.*` are often marked **provided** — your host app must supply them.
+* Re-run `curl` + `mvn clean install` whenever your service’s OpenAPI spec changes.
+* Optional vendor extension `x-class-extra-annotation` can add annotations (e.g., Jackson or Lombok) on generated wrappers.
+
+---
+
+## 10) Folder Structure (Suggested)
+
+```
+your-service-client/
+ ├─ src/main/java/<your/base>/openapi/client/common/
+ │   ├─ ServiceClientResponse.java
+ │   └─ ClientErrorDetail.java
+ ├─ src/main/java/<your/base>/openapi/client/adapter/
+ │   └─ YourClientAdapter.java
+ ├─ src/main/resources/openapi-templates/
+ │   ├─ api_wrapper.mustache
+ │   └─ model.mustache
+ ├─ src/main/resources/your-api-docs.yaml
+ └─ pom.xml
+```
+
+---
+
+✅ With this setup, your client project generates **type-safe wrappers** that align with `ServiceResponse<T>` from the server side, without any boilerplate duplication.
diff --git a/docs/adoption/server-side-adoption.md b/docs/adoption/server-side-adoption.md
