Skip to content

Commit c6cc0ef

Browse files
committed
docs: rewrite homepage to highlight project purpose and adoption flow
- Replaced generic "site is generated from repo" text with a clear intro - Added Problem → Solution → Benefits structure for better clarity - Kept links to Adoption Guides, Quick Start, and GitHub repo - Improved readability so visitors instantly understand what the project does
1 parent 617c704 commit c6cc0ef

File tree

1 file changed

+45
-2
lines changed

1 file changed

+45
-2
lines changed

docs/index.md

Lines changed: 45 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -8,13 +8,56 @@ nav_order: 1
88

99
Welcome! 👋
1010

11-
This site is generated from the
12-
[`spring-boot-openapi-generics-clients`](https://github.com/bsayli/spring-boot-openapi-generics-clients) repository.
11+
This project demonstrates how to extend **OpenAPI Generator** with **generics-aware wrappers**, avoiding duplicated
12+
response models and keeping client code clean and type-safe.
13+
14+
---
15+
16+
## 🚩 Problem
17+
18+
By default, **OpenAPI Generator does not support generics**. When backend teams use a generic response wrapper like
19+
`ServiceResponse<T>`, the generator produces **one full wrapper per endpoint**, duplicating fields such as `status`,
20+
`message`, and `errors`.
21+
22+
This causes:
23+
24+
* ❌ Dozens of nearly identical classes
25+
* ❌ High maintenance overhead
26+
* ❌ Boilerplate code scattered across clients
27+
28+
---
29+
30+
## 💡 Solution
31+
32+
This project shows how to:
33+
34+
* Mark wrapper schemas in OpenAPI using a small **Springdoc customizer**.
35+
* Provide a **tiny Mustache template overlay** so the generator emits **thin shells** extending a reusable generic base.
36+
* Preserve **compile-time type safety** while removing repetitive wrappers.
37+
38+
Result: Instead of duplicating fields, the generator creates wrappers like:
39+
40+
```java
41+
public class ServiceResponseCustomerDto
42+
extends ServiceClientResponse<CustomerDto> {
43+
}
44+
```
45+
46+
---
47+
48+
## ✅ Benefits
49+
50+
* Strong typing without boilerplate
51+
* A single generic base (`ServiceClientResponse<T>`) for all responses
52+
* Easier maintenance — update the base once, all clients benefit
53+
* Clean, consistent contracts across microservices
1354

1455
---
1556

1657
## 📘 Adoption Guides
1758

59+
Choose one of the following to integrate this pattern into your own project:
60+
1861
* [Server-Side Adoption](adoption/server-side-adoption.md)
1962
* [Client-Side Adoption](adoption/client-side-adoption.md)
2063

0 commit comments

Comments
 (0)