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

[bsayli]

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

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

---

Hi everyone 👋

This repository has evolved into a contract‑first, generics‑aware OpenAPI platform.

It is no longer a sample project — it is a deterministic architecture for producing and consuming APIs where:

• contracts are the single source of truth
• OpenAPI is a projection (not authority)
• generated code is disposable

---

🧠 Core Idea

At the center of the system is a shared canonical contract:

openapi-generics-contract

This module defines:

• ServiceResponse<T> — unified success envelope
• Page<T>, Meta, Sort — pagination primitives
• RFC 9457 Problem Details extensions

This contract is:

• used directly by the server
• reused implicitly by generated clients

OpenAPI is treated as a deterministic projection layer, not the source of truth.

---

⚙️ Platform Structure

The system is built as a platform with clear boundaries:

Server entry point

openapi-generics-server-starter
  └── openapi-generics-contract

• Spring Boot integration
• Contract → OpenAPI projection
• Generic type resolution
• Schema enrichment via vendor extensions

Client entry point

openapi-generics-java-codegen-parent
  ├── openapi-generics-java-codegen
  └── openapi-generics-contract

• OpenAPI → code generation
• Template system (Mustache overlays)
• Deterministic wrapper generation

---

🧩 What problem does this solve?

Typical OpenAPI setups with { data, meta } envelopes break down when generics are introduced:

• generics are erased
• envelopes are duplicated per endpoint
• model count explodes
• clients drift from server semantics

This platform ensures:

• single envelope definition (ServiceResponse<T>)
• preserved nested generics (ServiceResponse<Page<T>>)
• thin wrapper generation instead of duplicated models
• deterministic evolution across server → spec → client

---

🏗 What the platform provides

• Contract module (openapi-generics-contract)

  • canonical response + paging + error model

• Server starter (openapi-generics-server-starter)

  • detects generics in controller signatures
  • projects them into OpenAPI 3.1
  • emits semantic vendor extensions

• Generator layer (openapi-generics-java-codegen)

  • consumes enriched OpenAPI
  • generates thin wrappers
  • preserves generic bindings

• Parent distribution (openapi-generics-java-codegen-parent)

  • provides ready-to-use generator setup

---

🔁 Key principle

Java contract is the authority. OpenAPI is a projection.

This avoids:

• duplication across layers
• schema drift
• generator ambiguity

---

🤔 Discussion prompts

I’d love to hear how others approach this in real systems:

• Do you share a canonical response contract across services and clients?
• How do you handle nested generics safely?
• How do you prevent model explosion in OpenAPI clients?
• Do you rely on vendor extensions, or pure schema composition?
• How do you handle RFC 9457 Problem Details end‑to‑end?

Even short notes or trade‑offs are valuable.

---

📦 Repository

👉 https://github.com/blueprint-platform/openapi-generics

---

📖 Background

This work started from an exploration of generics-aware client generation and evolved into a platform-level architecture where:

• contracts are explicit and shared
• projection is deterministic
• generation is controlled

---

💬 If you're building or evaluating generics‑aware API systems, your perspective is highly valuable.

What worked, what failed, and what constraints did you hit?

Let’s surface real-world patterns — not just ideal ones.

[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.