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

[bsayli]

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

💭 How are you using generics-aware OpenAPI clients in your stack?

Hi everyone 👋

I’m curious how others are approaching generics-aware client generation.

This repository — spring-boot-openapi-generics-clients — demonstrates one production-ready implementation, but I’d love to hear how you are adapting similar concepts in your own projects:

• Are you customizing OpenAPI templates or using schema composition to express generics?
• Do you follow a unified { data, meta } response envelope pattern
• How do you handle Problem Details (RFC 9457) on the client side?

💭 Have you tried using generics or unified envelopes in your APIs?
Share your approach — even a short note helps others discover new patterns and trade-offs.

---

🚀 What this project provides

• ServiceResponse<T> and ServiceClientResponse<T> as reusable generic bases
• Thin, strongly-typed wrappers auto-generated from OpenAPI specs
• Cleaner, smaller, and easier-to-maintain client libraries
• Works out-of-the-box with Spring Boot 3.4, OpenAPI Generator 7.x, and Springdoc 2.8+
• Includes tests, adoption guides, and end-to-end examples for real-world use cases

🖼 Demo & Docs

Check the repository for:

• Swagger UI screenshots of the enhanced OpenAPI schema

• Examples of generated client classes — before vs after generics overlay

• Detailed adoption guides for both sides of the architecture:

  • Server-Side Adoption Guide
  • Client-Side Integration Guide

📖 Background

This work began with my Medium article:

👉 We Made OpenAPI Generator Think in Generics

It has since evolved into a full reference project — complete with documentation, templates, and examples that demonstrate how to make OpenAPI Generator truly generics-aware.

---

💬 I’d love to hear your feedback, questions, or real-world insights.
Drop a comment below — even a few words help others explore and refine this approach.

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