feat(customer-service): add optional support for extra class annotations in OpenAPI wrappers

Introduced vendor extension `x-class-extra-annotation` to allow attaching optional annotations
(e.g., Jackson, Lombok) on generated wrapper classes. This is disabled by default and only applied
when configured via `app.openapi.wrapper.class-extra-annotation`.

Author: barissayli

customer-service-client/README.md

@@ -434,7 +434,40 @@ It enqueues responses for **all CRUD operations** and asserts correct mapping in
   curl -s http://localhost:8084/customer-service/v3/api-docs.yaml \
     -o src/main/resources/customer-api-docs.yaml
   mvn -q clean install
-  ```
+  ``` 
+
+---
+
+### ⚙️ Optional: Extra Class Annotations
+
+The generator also supports an **optional vendor extension** to attach annotations directly on top of the generated
+wrapper classes.
+
+For example, if the OpenAPI schema contains:
+
+```yaml
+components:
+  schemas:
+    ServiceResponseCustomerDeleteResponse:
+      type: object
+      x-api-wrapper: true
+      x-api-wrapper-datatype: CustomerDeleteResponse
+      x-class-extra-annotation: "@com.fasterxml.jackson.annotation.JsonIgnoreProperties(ignoreUnknown = true)"
+```
+
+The generated wrapper becomes:
+
+```java
+
+@com.fasterxml.jackson.annotation.JsonIgnoreProperties(ignoreUnknown = true)
+public class ServiceResponseCustomerDeleteResponse
+        extends io.github.bsayli.openapi.client.common.ServiceClientResponse<CustomerDeleteResponse> {
+}
+```
+
+By default this feature is **not required** and we recommend using the plain `ServiceClientResponse<T>` wrappers
+as-is. However, the hook is available if your project needs to enforce additional annotations (e.g., Jackson, Lombok)
+on top of generated wrapper classes.
 
 ---
 

customer-service/README.md

@@ -218,6 +218,10 @@ mvn test
 * Provides **unit tests** for both controller and service layers.
 * Profiles: `local` (default) and `dev` available — can be extended per environment.
 * Focused on clarity and minimal setup.
+* Optional: You can attach extra annotations (e.g., Jackson) to generated wrapper classes by setting  
+  `app.openapi.wrapper.class-extra-annotation` in `application.yml`.  
+  See [customer-service-client README](../customer-service-client/README.md#-optional-extra-class-annotations) for
+  details.
 
 ---
 

customer-service/src/main/java/io/github/bsayli/customerservice/common/openapi/ApiResponseSchemaFactory.java

@@ -11,15 +11,25 @@ public final class ApiResponseSchemaFactory {
   private ApiResponseSchemaFactory() {}
 
   public static Schema<?> createComposedWrapper(String dataRefName) {
+    return createComposedWrapper(dataRefName, null);
+  }
+
+  public static Schema<?> createComposedWrapper(String dataRefName, String classExtraAnnotation) {
     var schema = new ComposedSchema();
     schema.setAllOf(
         List.of(
             new Schema<>().$ref("#/components/schemas/" + SCHEMA_SERVICE_RESPONSE),
             new ObjectSchema()
                 .addProperty(
                     PROP_DATA, new Schema<>().$ref("#/components/schemas/" + dataRefName))));
+
     schema.addExtension(EXT_API_WRAPPER, true);
     schema.addExtension(EXT_API_WRAPPER_DATATYPE, dataRefName);
+
+    if (classExtraAnnotation != null && !classExtraAnnotation.isBlank()) {
+      schema.addExtension(EXT_CLASS_EXTRA_ANNOTATION, classExtraAnnotation);
+    }
+
     return schema;
   }
 }

customer-service/src/main/java/io/github/bsayli/customerservice/common/openapi/OpenApiSchemas.java

@@ -17,6 +17,7 @@ public final class OpenApiSchemas {
   // Vendor extensions
   public static final String EXT_API_WRAPPER = "x-api-wrapper";
   public static final String EXT_API_WRAPPER_DATATYPE = "x-api-wrapper-datatype";
+  public static final String EXT_CLASS_EXTRA_ANNOTATION = "x-class-extra-annotation";
 
   private OpenApiSchemas() {}
 }

customer-service/src/main/java/io/github/bsayli/customerservice/common/openapi/autoreg/AutoWrapperSchemaCustomizer.java

@@ -5,10 +5,10 @@
 import io.github.bsayli.customerservice.common.openapi.introspector.ResponseTypeIntrospector;
 import java.util.Collections;
 import java.util.LinkedHashSet;
-import java.util.Map;
 import java.util.Set;
 import org.springdoc.core.customizers.OpenApiCustomizer;
 import org.springframework.beans.factory.ListableBeanFactory;
+import org.springframework.beans.factory.annotation.Value;
 import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.Configuration;
 import org.springframework.web.method.HandlerMethod;
@@ -18,20 +18,28 @@
 public class AutoWrapperSchemaCustomizer {
 
   private final Set<String> dataRefs;
+  private final String classExtraAnnotation;
 
   public AutoWrapperSchemaCustomizer(
-      ListableBeanFactory beanFactory, ResponseTypeIntrospector introspector) {
+      ListableBeanFactory beanFactory,
+      ResponseTypeIntrospector introspector,
+      @Value("${app.openapi.wrapper.class-extra-annotation:}") String classExtraAnnotation) {
+
     Set<String> refs = new LinkedHashSet<>();
-    Map<String, RequestMappingHandlerMapping> mappings =
-        beanFactory.getBeansOfType(RequestMappingHandlerMapping.class);
-    mappings
+    beanFactory
+        .getBeansOfType(RequestMappingHandlerMapping.class)
         .values()
         .forEach(
             rmh ->
                 rmh.getHandlerMethods().values().stream()
                     .map(HandlerMethod::getMethod)
                     .forEach(m -> introspector.extractDataRefName(m).ifPresent(refs::add)));
+
     this.dataRefs = Collections.unmodifiableSet(refs);
+    this.classExtraAnnotation =
+        (classExtraAnnotation == null || classExtraAnnotation.isBlank())
+            ? null
+            : classExtraAnnotation;
   }
 
   @Bean
@@ -42,7 +50,9 @@ public OpenApiCustomizer autoResponseWrappers() {
               String name = OpenApiSchemas.SCHEMA_SERVICE_RESPONSE + ref;
               openApi
                   .getComponents()
-                  .addSchemas(name, ApiResponseSchemaFactory.createComposedWrapper(ref));
+                  .addSchemas(
+                      name,
+                      ApiResponseSchemaFactory.createComposedWrapper(ref, classExtraAnnotation));
             });
   }
 }

customer-service/src/main/resources/application.yml

@@ -24,6 +24,8 @@ app:
   openapi:
     version: @project.version@
     base-url: "http://localhost:${server.port}${server.servlet.context-path:}"
+    #wrapper:
+    #class-extra-annotation: "@com.fasterxml.jackson.annotation.JsonIgnoreProperties(ignoreUnknown = true)"
 
 springdoc:
   default-consumes-media-type: application/json

customer-service/src/test/java/io/github/bsayli/customerservice/common/openapi/autoreg/AutoWrapperSchemaCustomizerTest.java

@@ -54,7 +54,7 @@ void registersSchemas_forDiscoveredRefs() throws Exception {
               };
             });
 
-    var customizerCfg = new AutoWrapperSchemaCustomizer(beanFactory, introspector);
+    var customizerCfg = new AutoWrapperSchemaCustomizer(beanFactory, introspector, null);
     OpenApiCustomizer customizer = customizerCfg.autoResponseWrappers();
 
     var openAPI = new OpenAPI().components(new Components());
@@ -79,7 +79,7 @@ void noRefs_noSchemasAdded() {
 
     when(beanFactory.getBeansOfType(RequestMappingHandlerMapping.class)).thenReturn(Map.of());
 
-    var customizerCfg = new AutoWrapperSchemaCustomizer(beanFactory, introspector);
+    var customizerCfg = new AutoWrapperSchemaCustomizer(beanFactory, introspector, null);
     OpenApiCustomizer customizer = customizerCfg.autoResponseWrappers();
 
     var openAPI = new OpenAPI().components(new Components());
@@ -92,6 +92,77 @@ void noRefs_noSchemasAdded() {
         "No schemas should be added when no refs exist");
   }
 
+  @Test
+  @DisplayName("Adds x-class-extra-annotation when classExtraAnnotation is provided")
+  void addsClassExtraAnnotation_whenConfigured() throws Exception {
+    var beanFactory = mock(ListableBeanFactory.class);
+    var handlerMapping = mock(RequestMappingHandlerMapping.class);
+    var introspector = mock(ResponseTypeIntrospector.class);
+
+    var controller = new SampleController();
+    Method foo = SampleController.class.getMethod("foo");
+
+    var handlerMap = new LinkedHashMap<RequestMappingInfo, HandlerMethod>();
+    handlerMap.put(mock(RequestMappingInfo.class), new HandlerMethod(controller, foo));
+
+    when(handlerMapping.getHandlerMethods()).thenReturn(handlerMap);
+    when(beanFactory.getBeansOfType(RequestMappingHandlerMapping.class))
+        .thenReturn(Map.of("rmh", handlerMapping));
+    when(introspector.extractDataRefName(any(Method.class))).thenReturn(Optional.of("FooRef"));
+
+    String classExtraAnn =
+        "@com.fasterxml.jackson.annotation.JsonIgnoreProperties(ignoreUnknown = true)";
+
+    var customizerCfg = new AutoWrapperSchemaCustomizer(beanFactory, introspector, classExtraAnn);
+    OpenApiCustomizer customizer = customizerCfg.autoResponseWrappers();
+
+    var openAPI = new OpenAPI().components(new Components());
+    customizer.customise(openAPI);
+
+    var schemaName = OpenApiSchemas.SCHEMA_SERVICE_RESPONSE + "FooRef";
+    var schema = openAPI.getComponents().getSchemas().get(schemaName);
+    assertNotNull(schema, "schema must exist for FooRef");
+    assertNotNull(schema.getExtensions(), "extensions map must be initialized");
+    assertEquals(
+        classExtraAnn,
+        schema.getExtensions().get(OpenApiSchemas.EXT_CLASS_EXTRA_ANNOTATION),
+        "x-class-extra-annotation must equal provided value");
+  }
+
+  @Test
+  @DisplayName("Does not add x-class-extra-annotation when classExtraAnnotation is blank")
+  void doesNotAddClassExtraAnnotation_whenBlank() throws Exception {
+    var beanFactory = mock(ListableBeanFactory.class);
+    var handlerMapping = mock(RequestMappingHandlerMapping.class);
+    var introspector = mock(ResponseTypeIntrospector.class);
+
+    var controller = new SampleController();
+    Method foo = SampleController.class.getMethod("foo");
+
+    var handlerMap = new LinkedHashMap<RequestMappingInfo, HandlerMethod>();
+    handlerMap.put(mock(RequestMappingInfo.class), new HandlerMethod(controller, foo));
+
+    when(handlerMapping.getHandlerMethods()).thenReturn(handlerMap);
+    when(beanFactory.getBeansOfType(RequestMappingHandlerMapping.class))
+        .thenReturn(Map.of("rmh", handlerMapping));
+    when(introspector.extractDataRefName(any(Method.class))).thenReturn(Optional.of("FooRef"));
+
+    var customizerCfg = new AutoWrapperSchemaCustomizer(beanFactory, introspector, "  ");
+    OpenApiCustomizer customizer = customizerCfg.autoResponseWrappers();
+
+    var openAPI = new OpenAPI().components(new Components());
+    customizer.customise(openAPI);
+
+    var schemaName = OpenApiSchemas.SCHEMA_SERVICE_RESPONSE + "FooRef";
+    var schema = openAPI.getComponents().getSchemas().get(schemaName);
+    assertNotNull(schema, "schema must exist for FooRef");
+
+    var ext = schema.getExtensions();
+    assertTrue(
+        ext == null || !ext.containsKey(OpenApiSchemas.EXT_CLASS_EXTRA_ANNOTATION),
+        "x-class-extra-annotation must not be present when blank");
+  }
+
   static class SampleController {
     public String foo() {
       return "ok";