feat(openapi): auto-register ServiceResponse<T> wrappers via controller introspection

- add AutoWrapperSchemaCustomizer to generate ServiceResponse{T} schemas automatically
- refactor ResponseTypeIntrospector with Java 21 guarded switch, depth guard, and debug logging
- support unwrapping ResponseEntity, CompletionStage/Future, DeferredResult/WebAsyncTask, and reactor wrappers (Mono/Flux)

Author: barissayli

customer-service-client/pom.xml

@@ -6,7 +6,7 @@
 
     <groupId>io.github.bsayli</groupId>
     <artifactId>customer-service-client</artifactId>
-    <version>0.6.0</version>
+    <version>0.6.1</version>
     <name>customer-service-client</name>
     <description>Generated client (RestClient) using generics-aware OpenAPI templates</description>
     <packaging>jar</packaging>

customer-service-client/src/main/resources/customer-api-docs.yaml

@@ -2,7 +2,7 @@ openapi: 3.1.0
 info:
   title: Customer Service API
   description: "Demo: type-safe generic API responses with OpenAPI"
-  version: 0.6.0
+  version: 0.6.1
 servers:
   - url: http://localhost:8084/customer-service
     description: Local service URL

customer-service/pom.xml

@@ -13,7 +13,7 @@
 
     <groupId>com.example.demo</groupId>
     <artifactId>customer-service</artifactId>
-    <version>0.6.0</version>
+    <version>0.6.1</version>
     <name>customer-service</name>
     <description>Demo service: Spring Boot 3.4 + Springdoc (OpenAPI) for generics-aware client generation</description>
 

customer-service/src/main/java/com/example/demo/common/openapi/introspector/ResponseTypeIntrospector.java

@@ -2,62 +2,73 @@
 
 import com.example.demo.common.api.response.ServiceResponse;
 import java.lang.reflect.Method;
-import java.util.List;
-import java.util.Objects;
 import java.util.Optional;
+import java.util.Set;
+import java.util.concurrent.CompletionStage;
+import java.util.concurrent.Future;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
 import org.springframework.core.ResolvableType;
 import org.springframework.http.ResponseEntity;
 import org.springframework.stereotype.Component;
+import org.springframework.web.context.request.async.DeferredResult;
+import org.springframework.web.context.request.async.WebAsyncTask;
 
 @Component
-public class ResponseTypeIntrospector {
+public final class ResponseTypeIntrospector {
 
-  private static final List<String> ASYNC_WRAPPERS =
-      List.of(
-          "reactor.core.publisher.Mono",
-          "reactor.core.publisher.Flux",
-          "java.util.concurrent.CompletionStage",
-          "java.util.concurrent.Future",
-          "org.springframework.web.context.request.async.DeferredResult",
-          "org.springframework.web.context.request.async.WebAsyncTask");
+  private static final Logger log = LoggerFactory.getLogger(ResponseTypeIntrospector.class);
+
+  private static final int MAX_UNWRAP_DEPTH = 8;
+
+  private static final Set<String> REACTOR_WRAPPERS =
+          Set.of("reactor.core.publisher.Mono", "reactor.core.publisher.Flux");
 
   public Optional<String> extractDataRefName(Method method) {
     if (method == null) return Optional.empty();
 
-    ResolvableType rt = ResolvableType.forMethodReturnType(method);
-
-    rt = unwrapIf(rt);
+    ResolvableType type = ResolvableType.forMethodReturnType(method);
+    type = unwrapToServiceResponse(type);
 
-    for (String wrapper : ASYNC_WRAPPERS) {
-      rt = unwrapIf(rt, wrapper);
-    }
+    Class<?> raw = type.resolve();
+    if (raw == null || !ServiceResponse.class.isAssignableFrom(raw)) return Optional.empty();
+    if (!type.hasGenerics()) return Optional.empty();
 
-    Class<?> raw = rt.resolve();
-    if (raw == null || !ServiceResponse.class.isAssignableFrom(raw)) {
-      return Optional.empty();
-    }
+    Class<?> dataClass = type.getGeneric(0).resolve();
+    Optional<String> ref = Optional.ofNullable(dataClass).map(Class::getSimpleName);
 
-    if (rt.getGenerics().length == 0) {
-      return Optional.empty();
+    if (log.isDebugEnabled()) {
+      log.debug("Introspected method [{}]: wrapper [{}], data [{}]",
+              method.toGenericString(), raw.getSimpleName(), ref.orElse("<none>"));
     }
 
-    Class<?> dataClass = rt.getGeneric(0).resolve();
-    return Optional.ofNullable(dataClass).map(Class::getSimpleName);
+    return ref;
   }
 
-  private ResolvableType unwrapIf(ResolvableType type) {
-    Class<?> raw = type.resolve();
-    if (raw != null && ResponseEntity.class.isAssignableFrom(raw)) {
-      return type.getGeneric(0);
+  private ResolvableType unwrapToServiceResponse(ResolvableType type) {
+    for (int guard = 0; guard < MAX_UNWRAP_DEPTH; guard++) {
+      Class<?> raw = type.resolve();
+      if (raw == null || ServiceResponse.class.isAssignableFrom(raw)) {
+        return type;
+      }
+      ResolvableType next = nextLayer(type, raw);
+      if (next == null) {
+        return type;
+      }
+      type = next;
     }
     return type;
   }
 
-  private ResolvableType unwrapIf(ResolvableType type, String wrapperClassName) {
-    Class<?> raw = type.resolve();
-    if (raw != null && Objects.equals(raw.getName(), wrapperClassName)) {
-      return type.getGeneric(0);
-    }
-    return type;
+  private ResolvableType nextLayer(ResolvableType current, Class<?> raw) {
+    return switch (raw) {
+      case Class<?> c when ResponseEntity.class.isAssignableFrom(c) -> current.getGeneric(0);
+      case Class<?> c when CompletionStage.class.isAssignableFrom(c)
+              || Future.class.isAssignableFrom(c) -> current.getGeneric(0);
+      case Class<?> c when DeferredResult.class.isAssignableFrom(c)
+              || WebAsyncTask.class.isAssignableFrom(c) -> current.getGeneric(0);
+      case Class<?> c when REACTOR_WRAPPERS.contains(c.getName()) -> current.getGeneric(0);
+      default -> null;
+    };
   }
-}
+}