feature(jackson3) add jackson3 support for spring generator (#22854)

* add 'useJackson3' option
* add 'useSpringBoot4' option
* add support for RestClient in spring-http-interfaces
* add 'jacksonPackage' template variable set from useJackson3 option

See #22294

Author: antechrestos

.github/workflows/samples-spring-jdk17.yaml

@@ -4,7 +4,10 @@ on:
   push:
     paths:
       - samples/openapi3/client/petstore/spring-cloud-3-with-optional
+      - samples/openapi3/client/petstore/spring-cloud-4-with-optional
+      - samples/client/petstore/spring-http-interface-springboot-4
       - samples/openapi3/server/petstore/springboot-3
+      - samples/openapi3/server/petstore/springboot-4
       - samples/server/petstore/springboot-api-response-examples
       - samples/server/petstore/springboot-lombok-data
       - samples/server/petstore/springboot-lombok-tostring
@@ -15,7 +18,10 @@ on:
   pull_request:
     paths:
       - samples/openapi3/client/petstore/spring-cloud-3-with-optional
+      - samples/openapi3/client/petstore/spring-cloud-4-with-optional
+      - samples/client/petstore/spring-http-interface-springboot-4
       - samples/openapi3/server/petstore/springboot-3
+      - samples/openapi3/server/petstore/springboot-4
       - samples/server/petstore/springboot-api-response-examples
       - samples/server/petstore/springboot-lombok-data
       - samples/server/petstore/springboot-lombok-tostring
@@ -33,8 +39,11 @@ jobs:
         sample:
           # clients
           - samples/openapi3/client/petstore/spring-cloud-3-with-optional
+          - samples/openapi3/client/petstore/spring-cloud-4-with-optional
+          - samples/client/petstore/spring-http-interface-springboot-4
           # servers
           - samples/openapi3/server/petstore/springboot-3
+          - samples/openapi3/server/petstore/springboot-4
           - samples/server/petstore/springboot-api-response-examples
           - samples/server/petstore/springboot-lombok-data
           - samples/server/petstore/springboot-lombok-tostring

bin/configs/spring-boot-4.yaml

@@ -0,0 +1,17 @@
+generatorName: spring
+outputDir: samples/openapi3/server/petstore/springboot-4
+inputSpec: modules/openapi-generator/src/test/resources/3_0/petstore.yaml
+templateDir: modules/openapi-generator/src/main/resources/JavaSpring
+additionalProperties:
+  groupId: org.openapitools.openapi3
+  documentationProvider: springdoc
+  artifactId: springboot
+  snapshotVersion: "true"
+  useSpringBoot4: true
+  useJackson3: true
+  useBeanValidation: true
+  withXml: true
+  hideGenerationTimestamp: "true"
+  generateConstructorWithAllArgs: true
+  generateBuilders: true
+  openApiNullable: false

bin/configs/spring-cloud-4-with-optional.yaml

@@ -0,0 +1,18 @@
+generatorName: spring
+library: spring-cloud
+outputDir: samples/openapi3/client/petstore/spring-cloud-4-with-optional
+inputSpec: modules/openapi-generator/src/test/resources/3_0/petstore.yaml
+templateDir: modules/openapi-generator/src/main/resources/JavaSpring
+additionalProperties:
+  groupId: org.openapitools.openapi3
+  documentationProvider: springdoc
+  artifactId: spring-cloud-oas4
+  useSpringBoot4: "true"
+  useJackson3: true
+  openApiNullable: false
+  dateLibrary: "java8"
+  useOptional: "true"
+  useSwaggerUI: "false"
+  hideGenerationTimestamp: "true"
+  documentationProvider: none
+  #optionalAcceptNullable: "false" # default to true

bin/configs/spring-http-interface-springboot-4.yaml

@@ -0,0 +1,21 @@
+generatorName: spring
+library: spring-http-interface
+outputDir: samples/client/petstore/spring-http-interface-springboot-4
+inputSpec: modules/openapi-generator/src/test/resources/3_0/spring/petstore-with-fake-endpoints-models-for-testing.yaml
+templateDir: modules/openapi-generator/src/main/resources/JavaSpring
+additionalProperties:
+  artifactId: spring-http-interface
+  snapshotVersion: "true"
+  hideGenerationTimestamp: "true"
+  modelNameSuffix: 'Dto'
+  generatedConstructorWithRequiredArgs: "false"
+  # documentation provider should be ignored
+  documentationProvider: "springdoc"
+  # annotation provider should be ignored
+  annotationLibrary: "swagger2"
+  # validation should be ignored
+  useBeanValidation: "true"
+  performBeanValidation: "true"
+  useSpringBoot4: "true"
+  useJackson3: true
+  openApiNullable: false

docs/generators/java-camel.md

@@ -107,12 +107,14 @@ These options may be applied as additional-properties (cli) or configOptions (pl
 |useEnumCaseInsensitive|Use `equalsIgnoreCase` when String for enum comparison| |false|
 |useFeignClientContextId|Whether to generate Feign client with contextId parameter.| |true|
 |useFeignClientUrl|Whether to generate Feign client with url parameter.| |true|
+|useJackson3|Set it in order to use jackson 3 dependencies (only allowed when `useSpringBoot4` is set and incompatible with `openApiNullable`).| |false|
 |useJakartaEe|whether to use Jakarta EE namespace instead of javax| |false|
 |useOneOfInterfaces|whether to use a java interface to describe a set of oneOf options, where each option is a class that implements the interface| |true|
 |useOptional|Use Optional container for optional parameters| |false|
 |useResponseEntity|Use the `ResponseEntity` type to wrap return values of generated API methods. If disabled, method are annotated using a `@ResponseStatus` annotation, which has the status of the first response declared in the Api definition| |true|
 |useSealed|Whether to generate sealed model interfaces and classes| |false|
 |useSpringBoot3|Generate code and provide dependencies for use with Spring Boot ≥ 3 (use jakarta instead of javax in imports). Enabling this option will also enable `useJakartaEe`.| |false|
+|useSpringBoot4|Generate code and provide dependencies for use with Spring Boot 4.x. (Use jakarta instead of javax in imports). Enabling this option will also enable `useJakartaEe`.| |false|
 |useSpringBuiltInValidation|Disable `@Validated` at the class level when using built-in validation.| |false|
 |useSpringController|Annotate the generated API as a Spring Controller| |false|
 |useSwaggerUI|Open the OpenApi specification in swagger-ui. Will also import and configure needed dependencies| |true|

docs/generators/spring.md

@@ -100,12 +100,14 @@ These options may be applied as additional-properties (cli) or configOptions (pl
 |useEnumCaseInsensitive|Use `equalsIgnoreCase` when String for enum comparison| |false|
 |useFeignClientContextId|Whether to generate Feign client with contextId parameter.| |true|
 |useFeignClientUrl|Whether to generate Feign client with url parameter.| |true|
+|useJackson3|Set it in order to use jackson 3 dependencies (only allowed when `useSpringBoot4` is set and incompatible with `openApiNullable`).| |false|
 |useJakartaEe|whether to use Jakarta EE namespace instead of javax| |false|
 |useOneOfInterfaces|whether to use a java interface to describe a set of oneOf options, where each option is a class that implements the interface| |true|
 |useOptional|Use Optional container for optional parameters| |false|
 |useResponseEntity|Use the `ResponseEntity` type to wrap return values of generated API methods. If disabled, method are annotated using a `@ResponseStatus` annotation, which has the status of the first response declared in the Api definition| |true|
 |useSealed|Whether to generate sealed model interfaces and classes| |false|
 |useSpringBoot3|Generate code and provide dependencies for use with Spring Boot ≥ 3 (use jakarta instead of javax in imports). Enabling this option will also enable `useJakartaEe`.| |false|
+|useSpringBoot4|Generate code and provide dependencies for use with Spring Boot 4.x. (Use jakarta instead of javax in imports). Enabling this option will also enable `useJakartaEe`.| |false|
 |useSpringBuiltInValidation|Disable `@Validated` at the class level when using built-in validation.| |false|
 |useSpringController|Annotate the generated API as a Spring Controller| |false|
 |useSwaggerUI|Open the OpenApi specification in swagger-ui. Will also import and configure needed dependencies| |true|

modules/openapi-generator/src/main/java/org/openapitools/codegen/languages/SpringCodegen.java

@@ -93,6 +93,7 @@ public class SpringCodegen extends AbstractJavaCodegen
     public static final String GENERATE_GENERIC_RESPONSE_ENTITY = "generateGenericResponseEntity";
     public static final String USE_ENUM_CASE_INSENSITIVE = "useEnumCaseInsensitive";
     public static final String USE_SPRING_BOOT3 = "useSpringBoot3";
+    public static final String USE_SPRING_BOOT4 = "useSpringBoot4";
     public static final String REQUEST_MAPPING_OPTION = "requestMappingMode";
     public static final String USE_REQUEST_MAPPING_ON_CONTROLLER = "useRequestMappingOnController";
     public static final String USE_REQUEST_MAPPING_ON_INTERFACE = "useRequestMappingOnInterface";
@@ -101,6 +102,10 @@ public class SpringCodegen extends AbstractJavaCodegen
     public static final String USE_SPRING_BUILT_IN_VALIDATION = "useSpringBuiltInValidation";
     public static final String USE_DEDUCTION_FOR_ONE_OF_INTERFACES = "useDeductionForOneOfInterfaces";
     public static final String SPRING_API_VERSION = "springApiVersion";
+    public static final String USE_JACKSON_3 = "useJackson3";
+    public static final String JACKSON2_PACKAGE = "com.fasterxml.jackson";
+    public static final String JACKSON3_PACKAGE = "tools.jackson";
+    public static final String JACKSON_PACKAGE = "jacksonPackage";
 
     @Getter
     public enum RequestMappingMode {
@@ -154,6 +159,8 @@ public enum RequestMappingMode {
     @Setter protected boolean useEnumCaseInsensitive = false;
     @Getter @Setter
     protected boolean useSpringBoot3 = false;
+    @Getter @Setter
+    protected boolean useSpringBoot4 = false;
     protected boolean generatedConstructorWithRequiredArgs = true;
     @Getter @Setter
     protected RequestMappingMode requestMappingMode = RequestMappingMode.controller;
@@ -163,6 +170,8 @@ public enum RequestMappingMode {
     protected boolean useSpringBuiltInValidation = false;
     @Getter @Setter
     protected boolean useDeductionForOneOfInterfaces = false;
+    @Getter @Setter
+    protected boolean useJackson3 = false;
 
     public SpringCodegen() {
         super();
@@ -281,6 +290,10 @@ public SpringCodegen() {
         cliOptions.add(CliOption.newBoolean(USE_SPRING_BOOT3,
                 "Generate code and provide dependencies for use with Spring Boot ≥ 3 (use jakarta instead of javax in imports). Enabling this option will also enable `useJakartaEe`.",
                 useSpringBoot3));
+        cliOptions.add(CliOption.newBoolean(USE_SPRING_BOOT4,
+                "Generate code and provide dependencies for use with Spring Boot 4.x. (Use jakarta instead of javax in imports). Enabling this option will also enable `useJakartaEe`.",
+                useSpringBoot4));
+        cliOptions.add(CliOption.newBoolean(USE_JACKSON_3, "Set it in order to use jackson 3 dependencies (only allowed when `" + USE_SPRING_BOOT4 + "` is set and incompatible with `"+OPENAPI_NULLABLE+"`).", useJackson3));
         cliOptions.add(CliOption.newBoolean(GENERATE_CONSTRUCTOR_WITH_REQUIRED_ARGS,
                 "Whether to generate constructors with required args for models",
                 generatedConstructorWithRequiredArgs));
@@ -463,8 +476,13 @@ public void processOpts() {
         additionalProperties.put("springHttpStatus", new SpringHttpStatusLambda());
 
         convertPropertyToBooleanAndWriteBack(USE_ENUM_CASE_INSENSITIVE, this::setUseEnumCaseInsensitive);
+        convertPropertyToBooleanAndWriteBack(USE_JACKSON_3, this::setUseJackson3);
         convertPropertyToBooleanAndWriteBack(USE_SPRING_BOOT3, this::setUseSpringBoot3);
-        if (isUseSpringBoot3()) {
+        convertPropertyToBooleanAndWriteBack(USE_SPRING_BOOT4, this::setUseSpringBoot4);
+        if(isUseSpringBoot3() && isUseSpringBoot4()){
+            throw new IllegalArgumentException("Choose between Spring Boot 3 and Spring Boot 4");
+        }
+        if (isUseSpringBoot3() || isUseSpringBoot4()) {
             if (DocumentationProvider.SPRINGFOX.equals(getDocumentationProvider())) {
                 throw new IllegalArgumentException(DocumentationProvider.SPRINGFOX.getPropertyName() + " is not supported with Spring Boot > 3.x");
             }
@@ -474,15 +492,30 @@ public void processOpts() {
             useJakartaEe = true;
             applyJakartaPackage();
         }
+        if(isUseJackson3() && !isUseSpringBoot4()){
+            throw new IllegalArgumentException("useJackson3 is only available with Spring Boot >= 4");
+        }
+        if(isUseJackson3() && isOpenApiNullable()){
+            throw new IllegalArgumentException("openApiNullable cannot be set with useJackson3");
+        }
+        if(this.useJackson3){
+            this.applyJackson3Package();
+        } else {
+            this.applyJackson2Package();
+        }
         convertPropertyToStringAndWriteBack(RESOURCE_FOLDER, this::setResourceFolder);
 
+
+        // override parent one
+        importMapping.put("JsonDeserialize", (useJackson3 ? JACKSON3_PACKAGE : JACKSON2_PACKAGE) + ".databind.annotation.JsonDeserialize");
+
         typeMapping.put("file", "org.springframework.core.io.Resource");
         importMapping.put("Nullable", "org.springframework.lang.Nullable");
         importMapping.put("org.springframework.core.io.Resource", "org.springframework.core.io.Resource");
         importMapping.put("DateTimeFormat", "org.springframework.format.annotation.DateTimeFormat");
         importMapping.put("ApiIgnore", "springfox.documentation.annotations.ApiIgnore");
         importMapping.put("ParameterObject", "org.springdoc.api.annotations.ParameterObject");
-        if (isUseSpringBoot3()) {
+        if (isUseSpringBoot3() || isUseSpringBoot4()) {
             importMapping.put("ParameterObject", "org.springdoc.core.annotations.ParameterObject");
         }
 
@@ -491,7 +524,9 @@ public void processOpts() {
             additionalProperties.put("delegate-method", true);
         }
 
-        if (isUseSpringBoot3()) {
+        if (isUseSpringBoot4()) {
+            supportingFiles.add(new SupportingFile("pom-sb4.mustache", "", "pom.xml"));
+        } else if (isUseSpringBoot3()) {
             supportingFiles.add(new SupportingFile("pom-sb3.mustache", "", "pom.xml"));
         } else {
             supportingFiles.add(new SupportingFile("pom.mustache", "", "pom.xml"));
@@ -657,6 +692,14 @@ public void processOpts() {
         supportsAdditionalPropertiesWithComposedSchema = true;
     }
 
+    protected void applyJackson2Package() {
+        writePropertyBack(JACKSON_PACKAGE, JACKSON2_PACKAGE);
+    }
+
+    protected void applyJackson3Package() {
+        writePropertyBack(JACKSON_PACKAGE, JACKSON3_PACKAGE);
+    }
+
     private boolean supportLibraryUseTags() {
         return SPRING_BOOT.equals(library) || SPRING_CLOUD_LIBRARY.equals(library);
     }

modules/openapi-generator/src/main/resources/JavaSpring/homeController.mustache

@@ -4,7 +4,7 @@ import org.springframework.context.annotation.Bean;
 import org.springframework.stereotype.Controller;
 import org.springframework.web.bind.annotation.RequestMapping;
 {{#sourceDocumentationProvider}}
-import com.fasterxml.jackson.dataformat.yaml.YAMLMapper;
+import {{jacksonPackage}}.dataformat.yaml.YAMLMapper;
 import org.springframework.beans.factory.annotation.Value;
 import org.springframework.core.io.Resource;
 import org.springframework.util.StreamUtils;

modules/openapi-generator/src/main/resources/JavaSpring/libraries/spring-boot/RFC3339DateFormat.mustache

@@ -1,6 +1,6 @@
 package {{basePackage}};
 
-import com.fasterxml.jackson.databind.util.StdDateFormat;
+import {{jacksonPackage}}.databind.util.StdDateFormat;
 
 import java.text.DateFormat;
 import java.text.FieldPosition;

modules/openapi-generator/src/main/resources/JavaSpring/libraries/spring-boot/application.mustache

@@ -1,6 +1,11 @@
 server.port={{serverPort}}
 spring.jackson.date-format={{basePackage}}.RFC3339DateFormat
+{{#useSpringBoot4}}
+spring.jackson.datatype.datetime.WRITE_DATES_AS_TIMESTAMPS=false
+{{/useSpringBoot4}}
+{{^useSpringBoot4}}
 spring.jackson.serialization.WRITE_DATES_AS_TIMESTAMPS=false
+{{/useSpringBoot4}}
 {{#virtualService}}
 virtualan.datasource.driver-class-name=org.hsqldb.jdbcDriver
 virtualan.datasource.jdbcurl=jdbc:hsqldb:mem:dataSource