Spring Boot OpenAPI Generics Clients

A production-grade blueprint for generics-aware API clients built with Spring Boot and OpenAPI Generator.

Welcome! 👋

This project demonstrates a modern, generics-aware OpenAPI client generation pattern for Spring Boot 3.4+, featuring the unified { data, meta } response model and full nested generic support — from ServiceResponse<T> to ServiceResponse<Page<T>>.

---

💡 Overview

Using Springdoc on the backend and OpenAPI Generator 7.17.0 on the client side, this setup enables seamless code generation where all responses are type-safe, clean, and boilerplate-free.

public class ServiceResponseCustomerDto
        extends ServiceClientResponse<CustomerDto> {
}

Each generated client wrapper now automatically supports nested generic envelopes such as:

ServiceClientResponse<Page<CustomerDto>>

---

✅ Key Features

• Unified response model: { data, meta } replaces legacy status/message/errors structure.
• Nested generics support: Handles both ServiceResponse<T> and ServiceResponse<Page<T>>.
• RFC 9457 compliant errors: All non-2xx responses are mapped into ProblemDetail and thrown as ClientProblemException.
• Generics-aware OpenAPI Generator overlay: Mustache templates produce thin, type-safe wrappers.
• Simple integration: Works with any Spring Boot service exposing /v3/api-docs.yaml.

---

🧩 Architecture

[customer-service]  →  publishes OpenAPI spec (/v3/api-docs.yaml)
         │
         └──►  [customer-service-client]  →  generates thin wrappers extending ServiceClientResponse<T>
                       │
                       └──►  used by consumer microservices via adapters

---

🚀 Quick Start

# Run the backend
cd customer-service && mvn spring-boot:run

# Generate the OpenAPI client
cd ../customer-service-client && mvn clean install

Generated wrappers appear under:

target/generated-sources/openapi/src/gen/java

Each class extends ServiceClientResponse<T> and is compatible with the { data, meta } response structure.

---

🧱 Example Response

{
  "data": {
    "customerId": 1,
    "name": "Jane Doe",
    "email": "jane@example.com"
  },
  "meta": {
    "serverTime": "2025-01-01T12:34:56Z",
    "sort": []
  }
}

Client usage:

ServiceClientResponse<CustomerDto> response = api.getCustomer(1);
CustomerDto dto = response.getData();
Instant serverTime = response.getMeta().serverTime();

---

⚙️ Toolchain

Component	Version	Purpose
Java	21	Language baseline
Spring Boot	3.4.11	REST + OpenAPI provider
Springdoc	2.8.13	OpenAPI 3.1 integration
OpenAPI Generator	7.17.0	Generics-aware client generation
HttpClient5	5.5	Production-grade HTTP backend

---

📚 Learn More

• Server-Side Adoption
• Client-Side Adoption

---

🔗 References & External Links

• 🌐 GitHub Repository
• 📘 Medium — We Made OpenAPI Generator Think in Generics

---

✅ With this setup, you get end-to-end generics awareness, clean { data, meta } responses, nested generic wrappers, and unified error handling — all generated automatically.