You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
fix customer-service error handling and align client/OpenAPI contract structure
- unify broken request exception handling under ApiRequestExceptionHandler
- restore RFC 9457 problem mapping for validation, bad request, type mismatch, not found, method not allowed, and internal error cases
- expand controller integration tests for success and error scenarios
- remove incorrect GlobalErrorResponsesCustomizer-based error schema approach
- switch client problem decoding to Spring ProblemDetail
- harden client fallback handling for non-json, unparsable, empty, and status-unavailable upstream responses
- fix fallback problem type URNs to use customer-service-client namespace
- rename generic client packages to customer-service-specific package structure
- align generated package naming for multi-client usage
- add Javadocs and clarify contract-aware OpenAPI wrapper registration
- refresh docs for api-contract Maven Central usage and updated module flow
Generated Java client that **reuses the canonical contract** and preserves generics
68
68
without duplicating envelopes or paging models.
69
69
70
70
---
71
71
72
72
## ⚡ Quick Start
73
73
74
-
This repository uses an **aggregator (root) build** to guarantee that the shared **`api-contract`** module is always available to both the server and the client.
75
-
For first-time users, **start from the repo root**.
74
+
The shared `api-contract` module is published to Maven Central as `0.7.7`,
75
+
so individual modules can now be built and run independently without requiring
76
+
a root-level bootstrap step just to make the contract available locally.
76
77
77
78
---
78
79
79
-
### ✅ Option A — Recommended (Deterministic, First-Time Setup)
80
+
### ✅ Option A — Recommended for Normal Use
80
81
81
-
This is the **canonical way** to get everything running after cloning the repository.
82
-
It installs `api-contract` locally and builds all modules in the correct order.
82
+
Build and run modules directly in their own scope:
83
83
84
84
```bash
85
-
# 1) Build everything once from the repo root
86
-
mvn -q -ntp clean install
87
-
88
-
# 2) Run the backend service
89
-
cd customer-service && mvn -q -ntp spring-boot:run
85
+
cd customer-service
86
+
mvn -q -ntp clean package
87
+
java -jar target/customer-service-*.jar
90
88
```
91
89
92
-
At this point:
90
+
This works because:
93
91
94
-
*`api-contract` is installed into your local Maven repository
95
-
*`customer-service` is running
96
-
*`customer-service-client` has been generated and compiled
97
-
98
-
No additional setup is required.
92
+
*`api-contract:0.7.7` is resolved directly from Maven Central
93
+
* no prior local installation step is required
94
+
* the service can now be treated like a normal standalone module
99
95
100
96
---
101
97
102
98
### 🔄 Option B — Regenerate the Client from the Live OpenAPI Spec
103
99
104
-
Use this flow **only when you change the server contract** and want to regenerate
100
+
Use this flow when you change the server contract and want to regenerate
They are **automatically added to compilation** via `build-helper-maven-plugin`.
133
+
They are automatically added to compilation via `build-helper-maven-plugin`.
138
134
139
135
---
140
136
141
137
### 📝 Notes
142
138
143
-
* You do **not** need to manually build or install `api-contract`.
144
-
The root build handles this by design.
145
-
* If you skip the root build and run the client directly, the build may fail
146
-
because `api-contract` is not yet available.
147
-
* For CI and local parity, all commands use `-ntp` (no transfer progress).
139
+
* You do **not** need to manually install `api-contract` locally.
140
+
* The shared contract is consumed as **`io.github.bsayli:api-contract:0.7.7`** from Maven Central.
141
+
* Root-level builds are still useful for full repository verification, but they are no longer required just to make the contract resolvable.
142
+
* For CI and local parity, commands use `-ntp` (no transfer progress).
148
143
149
144
---
150
145
151
146
> **Rule of thumb:**
152
-
> - If you just cloned the repo → **build from root**
153
-
> - If you changed the API contract → **regenerate the client**
147
+
>
148
+
> * If you want to run or build a module normally → **run it directly**
149
+
> * If you changed the published API contract surface → **regenerate the client**
150
+
> * If you want full repository verification → **build from root**
154
151
155
152
---
156
153
@@ -187,8 +184,9 @@ This scales poorly and makes contract evolution painful.
187
184
188
185
---
189
186
190
-
> **Background:** The rationale behind the canonical `ServiceResponse<T>` contract is explained here (updated Jan 2026):
187
+
> **Background:** The rationale behind the canonical `ServiceResponse<T>` contract is explained here (updated Jan 2026):
191
188
> [We Made OpenAPI Generator Think in Generics](https://medium.com/@baris.sayli/type-safe-generic-api-responses-with-spring-boot-3-4-openapi-generator-and-custom-templates-ccd93405fb04)
0 commit comments