spring-http-interface: introduce springHttpClientAdapter, fix paramDoc.mustache (#19710)

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

---
### What
- Introduce `springHttpClientAdapter` for `spring-http-interface`
  - This property is used for selecting HTTP client implementation in Spring HTTP interfaces, with separate templates for each client configuration
- Added an `spring-http-interface`-specific **empty** `paramDoc.mustache`
---

### Why
- Enable selecting different HTTP client implementations when generating Spring HTTP client interfaces
- Provides additional flexibility for users who want to generate non-reactive Spring Boot applications.
---

### How
- `springHttpClientAdapter`: Allows users to choose between different HTTP client implementations used in `HttpInterfacesAbstractConfigurator`:
  - `web-client` (set by default, to ensure **backward compatibility**)
  - `rest-client`
  - `rest-template`
- Separate templates for each `HttpInterfacesAbstractConfigurator` implementation:
  - `httpInterfacesRestClientConfiguration.mustache`
  - `httpInterfacesRestTemplateConfiguration.mustache`
  - `httpInterfacesWebClientConfiguration.mustache`
- Log warning for configuration mismatch
  - When `reactive: false` is used in combination with the reactive `web-client`, it warns users of potential configuration mismatches, and suggests switching to `rest-template` or `rest-client` for non-reactive configurations.
- Remove unnecessary paramDoc
  - Added an `spring-http-interface`-specific **empty** `paramDoc.mustache` in `JavaSpring/libraries/spring-http-interface/paramDoc.mustache`
  - This prevents inheriting the `@Parameter` annotations from the default Spring template located at `JavaSpring/paramDoc.mustache`.
  - Otherwise, the generated code includes `@Parameter` annotations on request body parameters, which were causing compile errors due to missing imports

---

### Testing Done

- **Manual testing**: Verified that the generated code uses `WebClient`, `RestTemplate`, or `RestClient` based on the value of the `springHttpClientAdapter` property.
- **Tested different configurations**:
   - **`reactive: false` & `web-client`**: Logs a warning, suggesting the use of `rest-client` or `rest-template`.
   - **`springHttpClientAdapter: rest-template`**: Generates code with `RestTemplateAdapter` using the `httpInterfacesRestTemplateConfiguration.mustache`.
   - **`springHttpClientAdapter: web-client` (default)**: Generates code using `WebClientAdapter` from `httpInterfacesWebClientConfiguration.mustache` and ensures backward compatibility.
- **Tested `paramDoc.mustache` change**: Verified that the empty `paramDoc.mustache` prevents the generation of `@Parameter` annotations on request body parameters and resolves the compile errors caused by missing imports.

---

### PR checklist

- [ ] Read the [contribution guidelines](https://github.com/openapitools/openapi-generator/blob/master/CONTRIBUTING.md).
- [ ] Pull Request title clearly describes the work in the pull request and Pull Request description provides details about how to validate the work. Missing information here may result in delayed response from the community.
- [ ] Run the following to [build the project](https://github.com/OpenAPITools/openapi-generator#14---build-projects) and update samples:
  ```
  ./mvnw clean package
  ./bin/generate-samples.sh ./bin/configs/*.yaml
  ./bin/utils/export_docs_generators.sh
  ```
  (For Windows users, please run the script in [Git BASH](https://gitforwindows.org/))
  Commit all changed files.
  This is important, as CI jobs will verify _all_ generator outputs of your HEAD commit as it would merge with master.
  These must match the expectations made by your contribution.
  You may regenerate an individual generator by passing the relevant config(s) as an argument to the script, for example `./bin/generate-samples.sh bin/configs/java*`.
  IMPORTANT: Do **NOT** purge/delete any folders/files (e.g. tests) when regenerating the samples as manually written tests may be removed.
- [ ] File the PR against the [correct branch](https://github.com/OpenAPITools/openapi-generator/wiki/Git-Branches): `master` (upcoming `7.x.0` minor release - breaking changes with fallbacks), `8.0.x` (breaking changes without fallbacks)
- [ ] If your PR is targeting a particular programming language, @mention the [technical committee](https://github.com/openapitools/openapi-generator/#62---openapi-generator-technical-committee) members, so they are more likely to review the pull request.

* fix imports

* Update SpringCodegen.java

* fix docs and default value

* fix docs and default value

* revert to HttpServiceProxyFactory.builder for backward compatibility

* spring-http-interface: introduce `useHttpServiceProxyFactoryInterfacesConfiguration` config

* spring-http-interface: introduce `useHttpServiceProxyFactoryInterfacesConfigurator` config

* spring-http-interface: introduce `useHttpServiceProxyFactoryInterfacesConfigurator` config

* spring-http-interface: fix generated files

* remove unnecessary imports from httpServiceProxyFactoryInterfacesConfigurator.mustache and parentOverrides from spring-http-interface-useHttpServiceProxyFactoryInterfacesConfiguration.yaml

* remove unnecessary paramDoc.mustache, update `useHttpServiceProxyFactoryInterfacesConfigurator` parameter docs of `spring-http-interface` library

* [java][spring] Spring HTTP Interface library: Validate Spring Boot version (3 or 4) and fail early if unsupported

* Set `useSpringBoot3: "true"` for all sample configs using `library: spring-http-interface`

* Regenerate samples using `library: spring-http-interface`

* Update "spring-http-interface" docs "Spring 6 HTTP interfaces (testing)" -> "Spring 6 HTTP interfaces (testing). Requires Spring Boot 3 or 4." in java-camel.md and spring.md

---------

Co-authored-by: Bragolgirith <6455473+Bragolgirith@users.noreply.github.com>

Author: ibaranga

.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}});
     }
 }
 ```