Skip to content

Commit 042a149

Browse files
committed
reformat by google reformatter
1 parent 6414e06 commit 042a149

File tree

4 files changed

+543
-429
lines changed

4 files changed

+543
-429
lines changed

README.md

Lines changed: 23 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,8 @@
1717
</p>
1818

1919
**Type-safe client generation with Spring Boot & OpenAPI using generics.**
20-
This repository demonstrates how to extend OpenAPI Generator to support **nested generics** and the new unified `{ data, meta }` response model — eliminating duplicated wrappers and repetitive boilerplate.
20+
This repository demonstrates how to extend OpenAPI Generator to support **nested generics** and the new unified
21+
`{ data, meta }` response model — eliminating duplicated wrappers and repetitive boilerplate.
2122

2223
---
2324

@@ -34,20 +35,24 @@ This repository demonstrates how to extend OpenAPI Generator to support **nested
3435
* 📘 [Adoption Guides](#-adoption-guides)
3536
* 🔗 [References & Links](#-references--links)
3637

37-
> *A practical reference for building fully generics-aware OpenAPI clients using Spring Boot 3.4, Java 21, and Mustache overlays.*
38+
> *A practical reference for building fully generics-aware OpenAPI clients using Spring Boot 3.4, Java 21, and Mustache
39+
overlays.*
3840

3941
---
4042

4143
## 📦 Modules in this Repository
4244

4345
* [**customer-service**](customer-service/README.md) — sample backend exposing `/v3/api-docs.yaml`
44-
* [**customer-service-client**](customer-service-client/README.md) — generated OpenAPI client with generics-aware wrappers
46+
* [**customer-service-client**](customer-service-client/README.md) — generated OpenAPI client with generics-aware
47+
wrappers
4548

4649
---
4750

4851
## 🚀 Problem & Motivation
4952

50-
OpenAPI Generator doesn’t natively understand **generic types**. When backend responses use envelopes like `ServiceResponse<T>`, the generator produces one wrapper per endpoint, duplicating fields (`status`, `message`, `errors`, or now `data`, `meta`).
53+
OpenAPI Generator doesn’t natively understand **generic types**. When backend responses use envelopes like
54+
`ServiceResponse<T>`, the generator produces one wrapper per endpoint, duplicating fields (`status`, `message`,
55+
`errors`, or now `data`, `meta`).
5156

5257
This leads to:
5358

@@ -61,12 +66,14 @@ This leads to:
6166

6267
This repository defines a **complete pattern** for Spring Boot + OpenAPI Generator:
6368

64-
* On the **server side**, a `Springdoc` customizer automatically marks generic wrappers (`ServiceResponse<T>`) with vendor extensions:
69+
* On the **server side**, a `Springdoc` customizer automatically marks generic wrappers (`ServiceResponse<T>`) with
70+
vendor extensions:
6571

6672
* `x-api-wrapper`
6773
* `x-api-wrapper-datatype`
6874
* `x-data-container` / `x-data-item`
69-
* On the **client side**, Mustache overlays generate **thin wrappers** extending the reusable generic base class `ServiceClientResponse<T>`.
75+
* On the **client side**, Mustache overlays generate **thin wrappers** extending the reusable generic base class
76+
`ServiceClientResponse<T>`.
7077

7178
Example generated wrapper:
7279

@@ -76,14 +83,15 @@ public class ServiceResponseCustomerDto
7683
}
7784
```
7885

79-
This new structure supports **nested generics** like `ServiceClientResponse<Page<CustomerDto>>` and includes both `data` and `meta` sections.
86+
This new structure supports **nested generics** like `ServiceClientResponse<Page<CustomerDto>>` and includes both `data`
87+
and `meta` sections.
8088

8189
---
8290

8391
## ⚙️ New Architecture Highlights
8492

8593
| Layer | Description |
86-
| --------------------- | ----------------------------------------------------------------------------------------------- |
94+
|-----------------------|-------------------------------------------------------------------------------------------------|
8795
| **Server (Producer)** | Publishes `/v3/api-docs.yaml` via Springdoc; marks generic wrappers with vendor extensions |
8896
| **Client (Consumer)** | Uses OpenAPI Generator 7.16.0 with custom Mustache templates to produce generics-aware wrappers |
8997
| **Envelope Model** | Unified `{ data, meta }` response model; compatible with `ProblemDetail` (RFC 7807) for errors |
@@ -140,7 +148,7 @@ Instant serverTime = response.getMeta().serverTime();
140148
## 🧩 Tech Stack
141149

142150
| Component | Version | Purpose |
143-
| --------------------- | ------- | ------------------------------ |
151+
|-----------------------|---------|--------------------------------|
144152
| **Java** | 21 | Language baseline |
145153
| **Spring Boot** | 3.4.10 | REST + OpenAPI provider |
146154
| **Springdoc** | 2.8.13 | OpenAPI 3.1 integration |
@@ -165,7 +173,9 @@ Instant serverTime = response.getMeta().serverTime();
165173
```java
166174
public interface CustomerClientAdapter {
167175
ServiceClientResponse<CustomerDto> createCustomer(CustomerCreateRequest request);
176+
168177
ServiceClientResponse<CustomerDto> getCustomer(Integer customerId);
178+
169179
ServiceClientResponse<Page<CustomerDto>> getCustomers();
170180
}
171181
```
@@ -186,8 +196,10 @@ See the detailed step-by-step setup under [`docs/adoption`](docs/adoption):
186196
## 🔗 References & Links
187197

188198
* 🌐 [GitHub Pages — Adoption Guides](https://bsayli.github.io/spring-boot-openapi-generics-clients/)
189-
* 📘 [Medium — Type-Safe Generic API Responses](https://medium.com/@baris.sayli/type-safe-generic-api-responses-with-spring-boot-3-4-openapi-generator-and-custom-templates-ccd93405fb04)
190-
* 💬 [Dev.to — Type-Safe OpenAPI Clients Without Boilerplate](https://dev.to/barissayli/spring-boot-openapi-generator-type-safe-generic-api-clients-without-boilerplate-3a8f)
199+
*
200+
📘 [Medium — Type-Safe Generic API Responses](https://medium.com/@baris.sayli/type-safe-generic-api-responses-with-spring-boot-3-4-openapi-generator-and-custom-templates-ccd93405fb04)
201+
*
202+
💬 [Dev.to — Type-Safe OpenAPI Clients Without Boilerplate](https://dev.to/barissayli/spring-boot-openapi-generator-type-safe-generic-api-clients-without-boilerplate-3a8f)
191203

192204
---
193205

0 commit comments

Comments
 (0)