spring-http-interface: introduce springHttpClientAdapter, fix paramDoc.mustache

.github/workflows/samples-jdk17.yaml

@@ -10,6 +10,7 @@ on:
       - samples/client/petstore/spring-http-interface/**
       - samples/client/petstore/spring-http-interface-reactive-noResponseEntity/**
       - samples/client/petstore/spring-http-interface-noResponseEntity/**
+      - samples/client/petstore/spring-http-interface-useHttpServiceProxyFactoryInterfacesConfigurator/**
       - samples/client/petstore/java/webclient-jakarta/**
       - samples/client/petstore/java/microprofile-rest-client-outer-enum/**
       # servers
@@ -29,6 +30,7 @@ on:
       - samples/client/petstore/spring-http-interface/**
       - samples/client/petstore/spring-http-interface-reactive-noResponseEntity/**
       - samples/client/petstore/spring-http-interface-noResponseEntity/**
+      - samples/client/petstore/spring-http-interface-useHttpServiceProxyFactoryInterfacesConfigurator/**
       - samples/client/petstore/java/webclient-jakarta/**
       - samples/client/petstore/java/microprofile-rest-client-outer-enum/**
       # servers
@@ -54,6 +56,7 @@ jobs:
           - samples/client/petstore/spring-http-interface
           - samples/client/petstore/spring-http-interface-reactive-noResponseEntity
           - samples/client/petstore/spring-http-interface-noResponseEntity
+          - samples/client/petstore/spring-http-interface-useHttpServiceProxyFactoryInterfacesConfigurator
           - samples/client/petstore/java/webclient-jakarta
           - samples/client/petstore/java/microprofile-rest-client-outer-enum
           # servers

bin/configs/spring-http-interface-noResponseEntity.yaml

@@ -17,3 +17,4 @@ additionalProperties:
   useBeanValidation: "true"
   performBeanValidation: "true"
   useResponseEntity: "false"
+  useSpringBoot3: "true"

bin/configs/spring-http-interface-reactive-noResponseEntity.yaml

@@ -16,4 +16,5 @@ additionalProperties:
   useBeanValidation: "true"
   performBeanValidation: "true"
   useResponseEntity: "false"
+  useSpringBoot3: "true"
 

bin/configs/spring-http-interface-reactive.yaml

@@ -15,4 +15,5 @@ additionalProperties:
   # validation should be ignored
   useBeanValidation: "true"
   performBeanValidation: "true"
+  useSpringBoot3: "true"
 

bin/configs/spring-http-interface-useHttpServiceProxyFactoryInterfacesConfiguration.yaml

@@ -0,0 +1,18 @@
+generatorName: spring
+library: spring-http-interface
+outputDir: samples/client/petstore/spring-http-interface-useHttpServiceProxyFactoryInterfacesConfigurator
+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-useHttpServiceProxyFactoryInterfacesConfigurator
+  snapshotVersion: "true"
+  hideGenerationTimestamp: "true"
+  # documentation provider should be ignored
+  documentationProvider: "springdoc"
+  # annotation provider should be ignored
+  annotationLibrary: "swagger2"
+  # validation should be ignored
+  useBeanValidation: "true"
+  performBeanValidation: "true"
+  useHttpServiceProxyFactoryInterfacesConfigurator: "true"
+  useSpringBoot3: "true"

bin/configs/spring-http-interface.yaml

@@ -16,3 +16,4 @@ additionalProperties:
   # validation should be ignored
   useBeanValidation: "true"
   performBeanValidation: "true"
+  useSpringBoot3: "true"

docs/generators/java-camel.md

@@ -73,7 +73,7 @@ These options may be applied as additional-properties (cli) or configOptions (pl
 |interfaceOnly|Whether to generate only API interface stubs without the server files.| |false|
 |invokerPackage|root package for generated code| |org.openapitools.api|
 |legacyDiscriminatorBehavior|Set to false for generators with better support for discriminators. (Python, Java, Go, PowerShell, C# have this enabled by default).|<dl><dt>**true**</dt><dd>The mapping in the discriminator includes descendent schemas that allOf inherit from self and the discriminator mapping schemas in the OAS document.</dd><dt>**false**</dt><dd>The mapping in the discriminator includes any descendent schemas that allOf inherit from self, any oneOf schemas, any anyOf schemas, any x-discriminator-values, and the discriminator mapping schemas in the OAS document AND Codegen validates that oneOf and anyOf schemas contain the required discriminator and throws an error if the discriminator is missing.</dd></dl>|false|
-|library|library template (sub-template)|<dl><dt>**spring-boot**</dt><dd>Spring-boot Server application.</dd><dt>**spring-cloud**</dt><dd>Spring-Cloud-Feign client with Spring-Boot auto-configured settings.</dd><dt>**spring-http-interface**</dt><dd>Spring 6 HTTP interfaces (testing)</dd></dl>|spring-boot|
+|library|library template (sub-template)|<dl><dt>**spring-boot**</dt><dd>Spring-boot Server application.</dd><dt>**spring-cloud**</dt><dd>Spring-Cloud-Feign client with Spring-Boot auto-configured settings.</dd><dt>**spring-http-interface**</dt><dd>Spring 6 HTTP interfaces (testing). Requires Spring Boot 3 or 4.</dd></dl>|spring-boot|
 |licenseName|The name of the license| |Unlicense|
 |licenseUrl|The URL of the license| |http://unlicense.org|
 |modelPackage|package for generated models| |org.openapitools.model|
@@ -109,6 +109,7 @@ 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|
+|useHttpServiceProxyFactoryInterfacesConfigurator|Generate HttpInterfacesAbstractConfigurator based on an HttpServiceProxyFactory instance (as opposed to a WebClient instance, when disabled) for generating Spring HTTP interfaces.| |false|
 |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|

docs/generators/spring.md

@@ -66,7 +66,7 @@ These options may be applied as additional-properties (cli) or configOptions (pl
 |interfaceOnly|Whether to generate only API interface stubs without the server files.| |false|
 |invokerPackage|root package for generated code| |org.openapitools.api|
 |legacyDiscriminatorBehavior|Set to false for generators with better support for discriminators. (Python, Java, Go, PowerShell, C# have this enabled by default).|<dl><dt>**true**</dt><dd>The mapping in the discriminator includes descendent schemas that allOf inherit from self and the discriminator mapping schemas in the OAS document.</dd><dt>**false**</dt><dd>The mapping in the discriminator includes any descendent schemas that allOf inherit from self, any oneOf schemas, any anyOf schemas, any x-discriminator-values, and the discriminator mapping schemas in the OAS document AND Codegen validates that oneOf and anyOf schemas contain the required discriminator and throws an error if the discriminator is missing.</dd></dl>|false|
-|library|library template (sub-template)|<dl><dt>**spring-boot**</dt><dd>Spring-boot Server application.</dd><dt>**spring-cloud**</dt><dd>Spring-Cloud-Feign client with Spring-Boot auto-configured settings.</dd><dt>**spring-http-interface**</dt><dd>Spring 6 HTTP interfaces (testing)</dd></dl>|spring-boot|
+|library|library template (sub-template)|<dl><dt>**spring-boot**</dt><dd>Spring-boot Server application.</dd><dt>**spring-cloud**</dt><dd>Spring-Cloud-Feign client with Spring-Boot auto-configured settings.</dd><dt>**spring-http-interface**</dt><dd>Spring 6 HTTP interfaces (testing). Requires Spring Boot 3 or 4.</dd></dl>|spring-boot|
 |licenseName|The name of the license| |Unlicense|
 |licenseUrl|The URL of the license| |http://unlicense.org|
 |modelPackage|package for generated models| |org.openapitools.model|
@@ -102,6 +102,7 @@ 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|
+|useHttpServiceProxyFactoryInterfacesConfigurator|Generate HttpInterfacesAbstractConfigurator based on an HttpServiceProxyFactory instance (as opposed to a WebClient instance, when disabled) for generating Spring HTTP interfaces.| |false|
 |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|

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

@@ -85,6 +85,8 @@ public class SpringCodegen extends AbstractJavaCodegen
     public static final String SPRING_BOOT = "spring-boot";
     public static final String SPRING_CLOUD_LIBRARY = "spring-cloud";
     public static final String SPRING_HTTP_INTERFACE = "spring-http-interface";
+    public static final String USE_HTTP_SERVICE_PROXY_FACTORY_INTERFACES_CONFIGURATOR = "useHttpServiceProxyFactoryInterfacesConfigurator";
+    public static final String HTTP_INTERFACES_CONFIGURATOR_DEPENDENCY = "httpInterfacesConfiguratorDependency";
     public static final String API_FIRST = "apiFirst";
     public static final String SPRING_CONTROLLER = "useSpringController";
     public static final String HATEOAS = "hateoas";
@@ -183,6 +185,7 @@ public enum RequestMappingMode {
     protected boolean useJackson3 = false;
     @Getter @Setter
     protected boolean additionalNotNullAnnotations = false;
+    @Setter boolean useHttpServiceProxyFactoryInterfacesConfigurator = false;
 
     public SpringCodegen() {
         super();
@@ -317,10 +320,14 @@ public SpringCodegen() {
 
         cliOptions.add(CliOption.newBoolean(USE_DEDUCTION_FOR_ONE_OF_INTERFACES, "whether to use deduction for generated oneOf interfaces", useDeductionForOneOfInterfaces));
         cliOptions.add(CliOption.newString(SPRING_API_VERSION, "Value for 'version' attribute in @RequestMapping (for Spring 7 and above)."));
+        cliOptions.add(CliOption.newString(USE_HTTP_SERVICE_PROXY_FACTORY_INTERFACES_CONFIGURATOR,
+            "Generate HttpInterfacesAbstractConfigurator based on an HttpServiceProxyFactory instance (as opposed to a WebClient instance, when disabled) for generating Spring HTTP interfaces.")
+            .defaultValue("false")
+        );
         supportedLibraries.put(SPRING_BOOT, "Spring-boot Server application.");
         supportedLibraries.put(SPRING_CLOUD_LIBRARY,
                 "Spring-Cloud-Feign client with Spring-Boot auto-configured settings.");
-        supportedLibraries.put(SPRING_HTTP_INTERFACE, "Spring 6 HTTP interfaces (testing)");
+        supportedLibraries.put(SPRING_HTTP_INTERFACE, "Spring 6 HTTP interfaces (testing). Requires Spring Boot 3 or 4.");
         setLibrary(SPRING_BOOT);
         final CliOption library = new CliOption(CodegenConstants.LIBRARY, CodegenConstants.LIBRARY_DESC)
                 .defaultValue(SPRING_BOOT);
@@ -542,7 +549,9 @@ public void processOpts() {
         } else {
             this.applyJackson2Package();
         }
+
         convertPropertyToStringAndWriteBack(RESOURCE_FOLDER, this::setResourceFolder);
+        convertPropertyToBooleanAndWriteBack(USE_HTTP_SERVICE_PROXY_FACTORY_INTERFACES_CONFIGURATOR, this::setUseHttpServiceProxyFactoryInterfacesConfigurator);
 
         convertPropertyToBooleanAndWriteBack(ADDITIONAL_NOT_NULL_ANNOTATIONS, this::setAdditionalNotNullAnnotations);
 
@@ -635,9 +644,23 @@ public void processOpts() {
                     }
                 }
             } else if (SPRING_HTTP_INTERFACE.equals(library)) {
-                supportingFiles.add(new SupportingFile("httpInterfacesConfiguration.mustache",
+                if (!(isUseSpringBoot3() || isUseSpringBoot4())) {
+                    throw new IllegalArgumentException("Library '" + SPRING_HTTP_INTERFACE + "' is only supported with Spring Boot 3 or 4");
+                }
+
+                String httpInterfacesAbstractConfiguratorFile = useHttpServiceProxyFactoryInterfacesConfigurator ?
+                    "httpServiceProxyFactoryInterfacesConfigurator.mustache" :
+                    "httpInterfacesConfiguration.mustache";
+
+                supportingFiles.add(new SupportingFile(httpInterfacesAbstractConfiguratorFile,
                         (sourceFolder + File.separator + configPackage).replace(".", java.io.File.separator), "HttpInterfacesAbstractConfigurator.java"));
                 writePropertyBack(USE_BEANVALIDATION, false);
+
+                writePropertyBack(HTTP_INTERFACES_CONFIGURATOR_DEPENDENCY,
+                    useHttpServiceProxyFactoryInterfacesConfigurator ?
+                    "HttpServiceProxyFactory" :
+                    reactive ? "WebClient" : "RestClient"
+                );
             }
         }
 

modules/openapi-generator/src/main/resources/JavaSpring/libraries/spring-http-interface/README.mustache

@@ -1,6 +1,6 @@
 # OpenAPI generated API stub
 
-[Spring Framework 6.1 HTTP Interface](https://docs.spring.io/spring-framework/docs/6.1.0/reference/html/integration.html#rest-http-interface)
+[Spring Framework 6.1 HTTP Interface](https://docs.spring.io/spring-framework/reference/integration/rest-clients.html#rest-http-interface)
 
 
 ## Overview
@@ -9,13 +9,13 @@ By using the [OpenAPI-Spec](https://openapis.org), you can easily generate an AP
 This is an example of building API stub interfaces in Java using the Spring framework.
 
 The stubs generated can be used in your existing Spring application for HTTP integration with other REST services
-To use auto-generated interfaces you have to create your own configuration which extends default abstract configurator & provide `{{#reactive}}WebClient{{/reactive}}{{^reactive}}RestClient{{/reactive}}` instance via constructor
+To use auto-generated interfaces you have to create your own configuration which extends default abstract configurator & provide `{{httpInterfacesConfiguratorDependency}}` instance via constructor
 ```java
 @Configuration
 public class MyConfiguration extends {{configPackage}}.HttpInterfacesAbstractConfigurator {
 
-    public MyConfiguration({{#reactive}}WebClient{{/reactive}}{{^reactive}}RestClient{{/reactive}} client) {
-        super(client);
+    public MyConfiguration({{httpInterfacesConfiguratorDependency}} my{{httpInterfacesConfiguratorDependency}}) { // separately created {{httpInterfacesConfiguratorDependency}} instance
+        super(my{{httpInterfacesConfiguratorDependency}});
     }
 }
 ```

modules/openapi-generator/src/main/resources/JavaSpring/libraries/spring-http-interface/httpServiceProxyFactoryInterfacesConfigurator.mustache

@@ -0,0 +1,35 @@
+/**
+* NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech) ({{{generatorVersion}}}).
+* https://openapi-generator.tech
+* Do not edit the class manually.
+*/
+package {{configPackage}};
+
+{{#apiInfo}}
+    {{#apis}}
+import {{apiPackage}}.{{classname}};
+    {{/apis}}
+{{/apiInfo}}
+
+import org.springframework.context.annotation.Bean;
+import org.springframework.web.service.invoker.HttpServiceProxyFactory;
+
+public abstract class HttpInterfacesAbstractConfigurator {
+
+    private final HttpServiceProxyFactory factory;
+
+    public HttpInterfacesAbstractConfigurator(final HttpServiceProxyFactory factory) {
+        this.factory = factory;
+    }
+
+{{#apiInfo}}
+{{#apis}}
+    @Bean(name = "{{configPackage}}.HttpInterfacesAbstractConfigurator.{{classVarName}}")
+    {{classname}} {{classVarName}}HttpProxy() {
+        return factory.createClient({{classname}}.class);
+    }
+
+{{/apis}}
+{{/apiInfo}}
+
+}

modules/openapi-generator/src/test/java/org/openapitools/codegen/java/spring/SpringCodegenTest.java

@@ -6621,6 +6621,7 @@ public void shouldNotHaveDocumentationAnnotationWhenUsingLibrarySpringHttpInterf
         codegen.setOpenAPI(openAPI);
         codegen.setOutputDir(output.getAbsolutePath());
         codegen.setLibrary(SPRING_HTTP_INTERFACE);
+        codegen.setUseSpringBoot3(true);
         codegen.setAnnotationLibrary(AnnotationLibrary.SWAGGER2);
         codegen.setDocumentationProvider(DocumentationProvider.SPRINGDOC);
 

samples/client/petstore/spring-http-interface-noResponseEntity/README.md

@@ -1,6 +1,6 @@
 # OpenAPI generated API stub
 
-[Spring Framework 6.1 HTTP Interface](https://docs.spring.io/spring-framework/docs/6.1.0/reference/html/integration.html#rest-http-interface)
+[Spring Framework 6.1 HTTP Interface](https://docs.spring.io/spring-framework/reference/integration/rest-clients.html#rest-http-interface)
 
 
 ## Overview
@@ -14,8 +14,8 @@ To use auto-generated interfaces you have to create your own configuration which
 @Configuration
 public class MyConfiguration extends org.openapitools.configuration.HttpInterfacesAbstractConfigurator {
 
-    public MyConfiguration(RestClient client) {
-        super(client);
+    public MyConfiguration(RestClient myRestClient) { // separately created RestClient instance
+        super(myRestClient);
     }
 }
 ```

samples/client/petstore/spring-http-interface-reactive-noResponseEntity/README.md

@@ -1,6 +1,6 @@
 # OpenAPI generated API stub
 
-[Spring Framework 6.1 HTTP Interface](https://docs.spring.io/spring-framework/docs/6.1.0/reference/html/integration.html#rest-http-interface)
+[Spring Framework 6.1 HTTP Interface](https://docs.spring.io/spring-framework/reference/integration/rest-clients.html#rest-http-interface)
 
 
 ## Overview
@@ -14,8 +14,8 @@ To use auto-generated interfaces you have to create your own configuration which
 @Configuration
 public class MyConfiguration extends org.openapitools.configuration.HttpInterfacesAbstractConfigurator {
 
-    public MyConfiguration(WebClient client) {
-        super(client);
+    public MyConfiguration(WebClient myWebClient) { // separately created WebClient instance
+        super(myWebClient);
     }
 }
 ```

samples/client/petstore/spring-http-interface-reactive/README.md

@@ -1,6 +1,6 @@
 # OpenAPI generated API stub
 
-[Spring Framework 6.1 HTTP Interface](https://docs.spring.io/spring-framework/docs/6.1.0/reference/html/integration.html#rest-http-interface)
+[Spring Framework 6.1 HTTP Interface](https://docs.spring.io/spring-framework/reference/integration/rest-clients.html#rest-http-interface)
 
 
 ## Overview
@@ -14,8 +14,8 @@ To use auto-generated interfaces you have to create your own configuration which
 @Configuration
 public class MyConfiguration extends org.openapitools.configuration.HttpInterfacesAbstractConfigurator {
 
-    public MyConfiguration(WebClient client) {
-        super(client);
+    public MyConfiguration(WebClient myWebClient) { // separately created WebClient instance
+        super(myWebClient);
     }
 }
 ```

samples/client/petstore/spring-http-interface-springboot-4/README.md

@@ -1,6 +1,6 @@
 # OpenAPI generated API stub
 
-[Spring Framework 6.1 HTTP Interface](https://docs.spring.io/spring-framework/docs/6.1.0/reference/html/integration.html#rest-http-interface)
+[Spring Framework 6.1 HTTP Interface](https://docs.spring.io/spring-framework/reference/integration/rest-clients.html#rest-http-interface)
 
 
 ## Overview
@@ -14,8 +14,8 @@ To use auto-generated interfaces you have to create your own configuration which
 @Configuration
 public class MyConfiguration extends org.openapitools.configuration.HttpInterfacesAbstractConfigurator {
 
-    public MyConfiguration(RestClient client) {
-        super(client);
+    public MyConfiguration(RestClient myRestClient) { // separately created RestClient instance
+        super(myRestClient);
     }
 }
 ```

samples/client/petstore/spring-http-interface-useHttpServiceProxyFactoryInterfacesConfigurator/.openapi-generator-ignore

@@ -0,0 +1,23 @@
+# OpenAPI Generator Ignore
+# Generated by openapi-generator https://github.com/openapitools/openapi-generator
+
+# Use this file to prevent files from being overwritten by the generator.
+# The patterns follow closely to .gitignore or .dockerignore.
+
+# As an example, the C# client generator defines ApiClient.cs.
+# You can make changes and tell OpenAPI Generator to ignore just this file by uncommenting the following line:
+#ApiClient.cs
+
+# You can match any string of characters against a directory, file or extension with a single asterisk (*):
+#foo/*/qux
+# The above matches foo/bar/qux and foo/baz/qux, but not foo/bar/baz/qux
+
+# You can recursively match patterns against a directory, file or extension with a double asterisk (**):
+#foo/**/qux
+# This matches foo/bar/qux, foo/baz/qux, and foo/bar/baz/qux
+
+# You can also negate patterns with an exclamation (!).
+# For example, you can ignore all files in a docs folder with the file extension .md:
+#docs/*.md
+# Then explicitly reverse the ignore rule for a single file:
+#!docs/README.md