docs: enhance README with badges, Quick Start, screenshots (Swagger + client wrapper) and feedback section

Author: bsayli

README.md

@@ -1,5 +1,10 @@
 # spring-boot-openapi-generics-clients
 
+![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)
+
 **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 duplicated wrappers, and keep client code clean.
 
@@ -9,6 +14,7 @@ This repository demonstrates how to teach OpenAPI Generator to work with generic
 
 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`).
+
 This creates:
 
 * ❌ Dozens of almost-identical classes
@@ -22,11 +28,57 @@ This creates:
 This project shows how to:
 
 * Customize **Springdoc** to mark wrapper schemas in OpenAPI
-* Add a **tiny Mustache partial** to make the generator emit thin shells extending a reusable generic base
+* Add a **tiny Mustache partial** so the generator emits thin shells extending a reusable generic base
 * Keep **compile-time type safety** without repetitive mappers
 
 ---
 
+## ⚡ Quick Start
+
+Run the sample service:
+
+```bash
+cd customer-service
+mvn spring-boot:run
+```
+
+Generate and build the client:
+
+```bash
+cd customer-service-client
+mvn clean install
+```
+
+Use the generated API:
+
+```java
+ApiClientResponse<CustomerCreateResponse> response =
+    customerControllerApi.create(request);
+```
+
+### 🖼 Demo 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)
+
+### 🖼 Generated Client Wrapper
+
+And here’s the corresponding generated client class showing the generic wrapper:
+
+![Generated client wrapper](docs/images/generated-client-wrapper.png)
+
+## 🛠 Tech Stack & Features
+
+* 🚀 **Java 21** — modern language features
+* 🍃 **Spring Boot 3.4** — microservice foundation
+* 📖 **Springdoc OpenAPI** — API documentation
+* 🔧 **OpenAPI Generator 7.x** — client code generation
+* 🧩 **Custom Mustache templates** — generics-aware wrappers
+* 🧪 **JUnit 5 + MockWebServer** — integration testing
+
+---
+
 ## 📂 Project Structure
 
 ```text
@@ -48,6 +100,28 @@ spring-boot-openapi-generics-clients/
 
 ---
 
+## 🔍 Why This Matters
+
+Without generics support, OpenAPI client generation creates bloated and repetitive code.
+By applying this approach:
+
+* Development teams **save time** maintaining response models
+* Client libraries become **cleaner and smaller**
+* Easier for **new developers** to understand the contract
+* Code stays **future-proof** when envelope fields evolve
+
+---
+
+## 💼 Use Cases
+
+This pattern is useful when:
+
+* You have **multiple microservices** with a shared response structure
+* You need to **evolve response envelopes** without breaking dozens of generated classes
+* You want **type safety** in generated clients but without boilerplate
+
+---
+
 ## 🔧 How to Run
 
 1. **Start the sample service**
@@ -83,3 +157,15 @@ This repository is based on my article:
 ## 🛡 License
 
 MIT
+
+---
+
+✅ **Note:** CLI examples should always be provided **on a single line**.
+If parameters include spaces or special characters, wrap them in quotes `"..."`.
+
+---
+
+## 💬 Feedback
+
+If you spot any mistakes in this README or have questions about the project, feel free to open an issue or start a discussion.
+I’m happy to improve the documentation and clarify concepts further!