[Spring] Spring HTTP Interface library (#14485)

Author: borsch

.github/workflows/samples-jdk17.yaml

@@ -6,6 +6,8 @@ on:
       - samples/openapi3/client/petstore/spring-cloud-3/**
       - samples/client/petstore/java-helidon-client/mp/**
       - samples/client/petstore/java-helidon-client/se/**
+      - samples/client/petstore/spring-http-interface-reactive/**
+      - samples/client/petstore/spring-http-interface/**
       # servers
       - samples/openapi3/server/petstore/springboot-3/**
       - samples/server/petstore/java-helidon-server/mp/**
@@ -16,6 +18,8 @@ on:
       - samples/openapi3/client/petstore/spring-cloud-3/**
       - samples/client/petstore/java-helidon-client/mp/**
       - samples/client/petstore/java-helidon-client/se/**
+      - samples/client/petstore/spring-http-interface-reactive/**
+      - samples/client/petstore/spring-http-interface/**
       # servers
       - samples/openapi3/server/petstore/springboot-3/**
       - samples/server/petstore/java-helidon-server/mp/**
@@ -32,10 +36,14 @@ jobs:
           - samples/openapi3/client/petstore/spring-cloud-3
           - samples/client/petstore/java-helidon-client/mp
           - samples/client/petstore/java-helidon-client/se
+          - samples/client/petstore/spring-http-interface-reactive
+          - samples/client/petstore/spring-http-interface
           # servers
           - samples/openapi3/server/petstore/springboot-3
           - samples/server/petstore/java-helidon-server/mp
           - samples/server/petstore/java-helidon-server/se
+          - samples/client/petstore/spring-http-interface-reactive
+          - samples/client/petstore/spring-http-interface
     steps:
       - uses: actions/checkout@v3
       - uses: actions/setup-java@v3

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

@@ -0,0 +1,11 @@
+generatorName: spring
+library: spring-http-interface
+outputDir: samples/client/petstore/spring-http-interface-reactive
+inputSpec: modules/openapi-generator/src/test/resources/2_0/petstore-with-fake-endpoints-models-for-testing.yaml
+templateDir: modules/openapi-generator/src/main/resources/JavaSpring
+additionalProperties:
+  artifactId: spring-http-interface-reactive
+  snapshotVersion: "true"
+  hideGenerationTimestamp: "true"
+  reactive: "true"
+

bin/configs/spring-http-interface.yaml

@@ -0,0 +1,10 @@
+generatorName: spring
+library: spring-http-interface
+outputDir: samples/client/petstore/spring-http-interface
+inputSpec: modules/openapi-generator/src/test/resources/2_0/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'

docs/generators/java-camel.md

@@ -64,7 +64,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>|true|
-|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></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)</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|

docs/generators/spring.md

@@ -57,7 +57,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>|true|
-|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></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)</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|

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

@@ -99,6 +99,7 @@ public class SpringCodegen extends AbstractJavaCodegen
     public static final String USE_TAGS = "useTags";
     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 API_FIRST = "apiFirst";
     public static final String SPRING_CONTROLLER = "useSpringController";
     public static final String HATEOAS = "hateoas";
@@ -247,6 +248,7 @@ public SpringCodegen() {
         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)");
         setLibrary(SPRING_BOOT);
         final CliOption library = new CliOption(CodegenConstants.LIBRARY, CodegenConstants.LIBRARY_DESC)
                 .defaultValue(SPRING_BOOT);
@@ -272,7 +274,7 @@ public String getHelp() {
 
     @Override
     public DocumentationProvider defaultDocumentationProvider() {
-        return DocumentationProvider.SPRINGDOC;
+        return SPRING_HTTP_INTERFACE.equals(library) ? DocumentationProvider.NONE : DocumentationProvider.SPRINGDOC;
     }
 
     public List<DocumentationProvider> supportedDocumentationProvider() {
@@ -343,6 +345,14 @@ public void processOpts() {
         // Please refrain from updating values of Config Options after super.ProcessOpts() is called
         super.processOpts();
 
+        if (SPRING_HTTP_INTERFACE.equals(library)) {
+            documentationProvider = DocumentationProvider.NONE;
+            annotationLibrary = AnnotationLibrary.NONE;
+            useJakartaEe=true;
+            additionalProperties.put(USE_JAKARTA_EE, useJakartaEe);
+            applyJakartaPackage();
+        }
+
         if (DocumentationProvider.SPRINGFOX.equals(getDocumentationProvider())) {
             LOGGER.warn("The springfox documentation provider is deprecated for removal. Use the springdoc provider instead.");
         }
@@ -402,8 +412,8 @@ public void processOpts() {
         }
 
         if (additionalProperties.containsKey(REACTIVE)) {
-            if (!SPRING_BOOT.equals(library)) {
-                throw new IllegalArgumentException("Currently, reactive option is only supported with Spring-boot");
+            if (SPRING_CLOUD_LIBRARY.equals(library)) {
+                throw new IllegalArgumentException("Currently, reactive option doesn't supported by Spring Cloud");
             }
             this.setReactive(Boolean.parseBoolean(additionalProperties.get(REACTIVE).toString()));
         }
@@ -537,7 +547,7 @@ public void processOpts() {
                 // @RequestMapping not supported with spring cloud openfeign.
                 setRequestMappingMode(RequestMappingMode.none);
                 additionalProperties.put(USE_FEIGN_CLIENT, "true");
-            } else {
+            } else if (SPRING_BOOT.equals(library)) {
                 apiTemplateFiles.put("apiController.mustache", "Controller.java");
                 if (containsEnums()) {
                     supportingFiles.add(new SupportingFile("converter.mustache",
@@ -561,10 +571,14 @@ public void processOpts() {
                             "SpringFoxConfiguration.java"));
                     }
                 }
+            } else if (SPRING_HTTP_INTERFACE.equals(library)) {
+                supportingFiles.add(new SupportingFile("httpInterfacesConfiguration.mustache",
+                    (sourceFolder + File.separator + configPackage).replace(".", java.io.File.separator), "HttpInterfacesAbstractConfigurator.java"));
+                writePropertyBack(USE_BEANVALIDATION, false);
             }
         }
 
-        if (!SPRING_CLOUD_LIBRARY.equals(library)) {
+        if (SPRING_BOOT.equals(library)) {
             supportingFiles.add(new SupportingFile("apiUtil.mustache",
                     (sourceFolder + File.separator + apiPackage).replace(".", java.io.File.separator), "ApiUtil.java"));
         }

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

@@ -0,0 +1,21 @@
+# OpenAPI generated API stub
+
+[Spring Framework 6 HTTP Interface](https://docs.spring.io/spring-framework/docs/6.0.0/reference/html/integration.html#rest-http-interface)
+
+
+## Overview
+This code was generated by the [OpenAPI Generator](https://openapi-generator.tech) project.
+By using the [OpenAPI-Spec](https://openapis.org), you can easily generate an API stub.
+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 `WebClient` instance via constructor
+```java
+@Configuration
+public class MyConfiguration extends {{configPackage}}.HttpInterfacesAbstractConfigurator {
+
+    public MyConfiguration(WebClient myWebClient) { // separately created WebClient instance
+        super(myWebClient);
+    }
+}
+```

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

@@ -0,0 +1,67 @@
+/**
+ * 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 {{package}};
+
+{{#imports}}import {{import}};
+{{/imports}}
+import org.springframework.http.ResponseEntity;
+import org.springframework.web.bind.annotation.*;
+import org.springframework.web.service.annotation.*;
+import org.springframework.web.multipart.MultipartFile;
+{{#reactive}}
+
+import org.springframework.http.codec.multipart.Part;
+import reactor.core.publisher.Flux;
+import reactor.core.publisher.Mono;
+{{/reactive}}
+
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+import {{javaxPackage}}.annotation.Generated;
+
+
+{{>generatedAnnotation}}
+{{#operations}}
+public interface {{classname}} {
+{{#operation}}
+
+    /**
+     * {{httpMethod}} {{{path}}}{{#summary}} : {{.}}{{/summary}}
+    {{#notes}}
+     * {{.}}
+    {{/notes}}
+     *
+    {{#allParams}}
+     * @param {{paramName}} {{description}}{{#required}} (required){{/required}}{{^required}} (optional{{#defaultValue}}, default to {{.}}{{/defaultValue}}){{/required}}
+    {{/allParams}}
+     * @return {{#responses}}{{message}} (status code {{code}}){{^-last}}
+     *         or {{/-last}}{{/responses}}
+    {{#isDeprecated}}
+     * @deprecated
+    {{/isDeprecated}}
+    {{#externalDocs}}
+     * {{description}}
+     * @see <a href="{{url}}">{{summary}} Documentation</a>
+    {{/externalDocs}}
+     */
+    {{#isDeprecated}}
+    @Deprecated
+    {{/isDeprecated}}
+    @HttpExchange(
+        method = "{{{httpMethod}}}",
+        value = "{{{path}}}"{{#vendorExtensions.x-accepts}},
+        accept = "{{{vendorExtensions.x-accepts}}}"{{/vendorExtensions.x-accepts}}{{#vendorExtensions.x-content-type}},
+        contentType = "{{{vendorExtensions.x-content-type}}}"{{/vendorExtensions.x-content-type}}
+    )
+    {{#responseWrapper}}{{.}}<{{/responseWrapper}}ResponseEntity<{{>returnTypes}}>{{#responseWrapper}}>{{/responseWrapper}} {{operationId}}(
+        {{#allParams}}{{>queryParams}}{{>pathParams}}{{>headerParams}}{{>bodyParams}}{{>formParams}}{{>cookieParams}}{{^-last}},
+        {{/-last}}{{/allParams}}
+    ){{#unhandledException}} throws Exception{{/unhandledException}};
+
+{{/operation}}
+}
+{{/operations}}

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

@@ -0,0 +1,38 @@
+/**
+* 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.reactive.function.client.WebClient;
+import org.springframework.web.reactive.function.client.support.WebClientAdapter;
+import org.springframework.web.service.invoker.HttpServiceProxyFactory;
+
+public abstract class HttpInterfacesAbstractConfigurator {
+
+    private final WebClient webClient;
+
+    public HttpInterfacesAbstractConfigurator(final WebClient webClient) {
+        this.webClient = webClient;
+    }
+
+{{#apiInfo}}
+{{#apis}}
+    @Bean(name = "{{configPackage}}.HttpInterfacesAbstractConfigurator.{{classVarName}}")
+    {{classname}} {{classVarName}}HttpProxy() {
+        HttpServiceProxyFactory factory = HttpServiceProxyFactory.builder(WebClientAdapter.forClient(webClient)).build();
+        return factory.createClient({{classname}}.class);
+    }
+
+{{/apis}}
+{{/apiInfo}}
+
+}

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

@@ -0,0 +1,98 @@
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+    <groupId>{{groupId}}</groupId>
+    <artifactId>{{artifactId}}</artifactId>
+    <packaging>jar</packaging>
+    <name>{{artifactId}}</name>
+    <version>{{artifactVersion}}</version>
+    <properties>
+        <java.version>17</java.version>
+        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+    </properties>
+{{#parentOverridden}}
+    <parent>
+        <groupId>{{{parentGroupId}}}</groupId>
+        <artifactId>{{{parentArtifactId}}}</artifactId>
+        <version>{{{parentVersion}}}</version>
+    </parent>
+{{/parentOverridden}}
+{{^parentOverridden}}
+    <parent>
+        <groupId>org.springframework.boot</groupId>
+        <artifactId>spring-boot-starter-parent</artifactId>
+        <version>3.0.1</version>
+        <relativePath/> <!-- lookup parent from repository -->
+    </parent>
+{{/parentOverridden}}
+
+    <build>
+        <plugins>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-compiler-plugin</artifactId>
+                <version>3.8.1</version>
+                <configuration>
+                    <source>${java.version}</source>
+                    <target>${java.version}</target>
+                </configuration>
+            </plugin>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-source-plugin</artifactId>
+                <version>3.2.1</version>
+                <executions>
+                    <execution>
+                        <id>attach-sources</id>
+                        <goals>
+                            <goal>jar-no-fork</goal>
+                        </goals>
+                    </execution>
+                </executions>
+            </plugin>
+        </plugins>
+    </build>
+
+    <dependencies>
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter-webflux</artifactId>
+        </dependency>
+        <!-- @Nullable annotation -->
+        <dependency>
+            <groupId>com.google.code.findbugs</groupId>
+            <artifactId>jsr305</artifactId>
+            <version>3.0.2</version>
+        </dependency>
+        <dependency>
+            <groupId>jakarta.validation</groupId>
+            <artifactId>jakarta.validation-api</artifactId>
+        </dependency>
+        {{#withXml}}
+        <!-- XML processing: Jackson -->
+        <dependency>
+          <groupId>jakarta.xml.bind</groupId>
+          <artifactId>jakarta.xml.bind-api</artifactId>
+        </dependency>
+        <dependency>
+          <groupId>com.fasterxml.jackson.dataformat</groupId>
+          <artifactId>jackson-dataformat-xml</artifactId>
+        </dependency>
+        {{/withXml}}
+        <dependency>
+            <groupId>com.fasterxml.jackson.datatype</groupId>
+            <artifactId>jackson-datatype-jsr310</artifactId>
+        </dependency>
+        {{#openApiNullable}}
+        <dependency>
+            <groupId>org.openapitools</groupId>
+            <artifactId>jackson-databind-nullable</artifactId>
+            <version>0.2.2</version>
+        </dependency>
+        {{/openApiNullable}}
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter-test</artifactId>
+            <scope>test</scope>
+        </dependency>
+    </dependencies>
+</project>