spring-boot-openapi-generics-clients — Production‑Ready, Type‑Safe API Clients with Generics

[bsayli]

Category: Announcements
Tags / labels: openapi, spring-boot, generics, client-generation, contracts

---

💭 How are you handling generics‑aware OpenAPI clients in production?

Hi everyone 👋

Over the last iterations, this repository has evolved into a contract‑first, production‑ready reference architecture for building type‑safe OpenAPI clients with generics — without duplicating envelopes or losing nested types during generation.

The key shift is the introduction of a shared canonical contract module:

api-contract

This module defines the single source of truth for:

• ServiceResponse<T> — unified success envelope
• Meta, Page<T>, Sort, SortDirection — paging & metadata primitives
• RFC 9457 extensions (ProblemExtensions, ErrorItem) — error details

Both server and client reuse this contract directly.

OpenAPI is no longer treated as a code generator of truth, but as a semantic bridge between producer and consumer.

---

🧠 What problem does this pattern solve?

Many teams standardize on a { data, meta } response envelope.

But once pagination and nested containers enter the picture, default OpenAPI generation tends to:

• erase generics
• duplicate response envelopes per endpoint
• explode the model count
• make client evolution painful

This project demonstrates how to:

• keep exactly one envelope definition
• preserve generics end‑to‑end (ServiceResponse<T>, ServiceResponse<Page<T>>)
• generate thin wrappers instead of duplicated models
• evolve contracts deterministically

---

🏗 What this project provides today

• api-contract — framework‑agnostic canonical contract shared by server and client

• Spring Boot producer publishing an enriched OpenAPI 3.1 spec

• OpenAPI schema enricher (OpenApiCustomizer) that:

  • detects ServiceResponse<T> in controller signatures
  • emits semantic vendor extensions (x-api-wrapper, x-data-container, …)

• OpenAPI Generator 7.x with Mustache overlays producing:

  • thin wrapper classes extending ServiceResponse<T>
  • preserved nested generics (Page<T>)

• RFC 9457‑first error handling decoded into ApiProblemException

• Adapter boundary so consumers never depend directly on generated APIs

This is not a demo — it is a reference implementation.

---

🤔 Discussion prompts

I’d love to hear how others are approaching similar problems in real systems:

• Are you sharing a canonical response contract across services and clients?
• Do you allow nested generics, and if so, how do you constrain them?
• How do you prevent envelope duplication in generated clients?
• Are you extending OpenAPI with vendor semantics, or relying on pure schema composition?
• How are you handling RFC 9457 Problem Details on the client side?

Even short notes or trade‑offs you’ve encountered are valuable.

---

📘 Docs & Guides

If you want to explore the full setup:

• 📦 Repository
  https://github.com/bsayli/spring-boot-openapi-generics-clients

• 🏗 Architecture Overview
  Generics‑aware flow from Spring Boot producer → OpenAPI → type‑safe client

• 📘 Adoption Guides

  • Server‑Side Adoption
    server-side-adoption
  • Client‑Side Adoption (Build Setup & Integration)
    client-side-adoption

---

📖 Background

This work started with the article:

👉 We Made OpenAPI Generator Think in Generics

Since then, the idea matured into a contract‑driven system where:

• contracts are explicit and shared
• generated code is disposable
• evolution is controlled

---

💬 If you’re using — or considering — generics‑aware API clients, I’d really value your perspective.

Share what worked, what didn’t, or what you’d do differently.
This discussion is meant to surface real‑world constraints, not just happy paths.

[mozinrat]

Is this solution fully compliant with OAS 3.1.1 specs OAI/OpenAPI-Specification#3601. Had a hard time making this work end to end. I.e generate openapi spec from controller -> use that in the client code.
I think the instance here is to take an openapi spec, manually augment it and then use that in client code, however if we can make the augmentation work at time of generation it would be great.

[bsayli]

Hi! Thanks for digging into this — getting “controller → spec → client” to work end-to-end with generic envelopes is still surprisingly tricky.

On the compliance side: the approach in this repo is OAS 3.1.x compatible, because the generated schemas remain valid OpenAPI/JSON Schema. However, it does not use $dynamicRef/$dynamicAnchor to model generics at the spec level. Instead, it uses vendor extensions (e.g., x-api-wrapper, x-api-wrapper-datatype, etc.) as an explicit hint for code generation.

So you can think of it as a practical compatibility layer:

• Producer (Springdoc) generates a standard OAS 3.1 spec, and at generation time we augment it based on the controller’s resolved generic types.
• Consumer (OpenAPI Generator) reads those vendor extensions via template overlays and produces thin, strongly-typed wrappers (e.g., ServiceClientResponse<Page<CustomerDto>>) without model explosion.

In other words, you’re right about the “intent”: many toolchains assume a manually-augmented spec. What this project aims to do is make that augmentation happen automatically during spec generation, so the client can stay fully aligned without manual edits.

If/when the ecosystem supports $dynamicRef end-to-end (Springdoc emitting it + OpenAPI Generator mapping it to Java generics), we can revisit and potentially drop the vendor-extension bridge.