Merge pull request #41 from Orbifoldt/main

Adding multipart/form-data support

Author: ricardozanini

README.md

@@ -276,6 +276,69 @@ org.acme.openapi.simple.api.DefaultApi/byeGet/CircuitBreaker/failureRatio=3.14
 org.acme.openapi.simple.api.DefaultApi/byeGet/CircuitBreaker/successThreshold=22
 ````
 
+## Sending multipart/form-data
+The rest client also supports request with mime-type multipart/form-data and, if the schema of the request body is known in advance, we can also automatically generate the models of the request bodies. 
+
+You need to add the following additional dependency to your `pom.xml`:
+```xml
+<dependency>
+  <groupId>io.quarkus</groupId>
+  <artifactId>quarkus-resteasy-multipart</artifactId>
+</dependency>
+```
+For any multipart/form-data operation a model for the request body will be generated. Each part of the multipart is a field in this model that is annotated with the following annotations:
+- `javax.ws.rs.FormParam`, where the value parameter denotes the part name, 
+- `org.jboss.resteasy.annotations.providers.multipart.PartType`, where the parameter is the jax-rs MediaType of the part (see below for details),
+- and, if the part contains a file, `org.jboss.resteasy.annotations.providers.multipart.PartFilename`, with a generated default parameter that will be passed as the fileName sub-header in the Content-Disposition header of the part.
+
+For example, the model for a request that requires a file, a string and some complex object will look like this: 
+```java
+public class MultipartBody {
+
+    @FormParam("file")
+    @PartType(MediaType.APPLICATION_OCTET_STREAM)
+    @PartFilename("defaultFileName")
+    public File file;
+
+    @FormParam("fileName")
+    @PartType(MediaType.TEXT_PLAIN)
+    public String fileName;
+
+    @FormParam("someObject")
+    @PartType(MediaType.APPLICATION_JSON)
+    public MyComplexObject someObject;
+}
+```
+
+Then in the client the `org.jboss.resteasy.annotations.providers.multipart.MultipartForm` annotation is added in front of the multipart parameter:
+```java
+@Path("/echo")
+@RegisterRestClient
+public interface MultipartService {
+    
+    @POST
+    @Consumes(MediaType.MULTIPART_FORM_DATA)
+    @Produces(MediaType.TEXT_PLAIN)
+    String sendMultipartData(@MultipartForm MultipartBody data);
+    
+}
+```
+See [Quarkus - Using the REST Client with Multipart](https://quarkus.io/guides/rest-client-multipart) and the [RESTEasy JAX-RS specifications](https://docs.jboss.org/resteasy/docs/4.7.5.Final/userguide/html_single/index.html) for more details.
+
+Importantly, if some multipart request bodies contain complex objects (i.e. non-primitives) you need to explicitly tell the Open API generator to create models for these objects by setting the `skip-form-model` property corresponding to your spec in the `application.properties` to `false`, e.g.:
+```properties
+quarkus.openapi-generator.codegen.spec."my-multipart-requests.yml".skip-form-model=false
+```
+
+### Default content-types according to OpenAPI Specification and limitations
+The [OAS 3.0](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#special-considerations-for-multipart-content) specifies the following default content-types for a multipart:
+- If the property is a primitive, or an array of primitive values, the default Content-Type is `text/plain`
+- If the property is complex, or an array of complex values, the default Content-Type is `application/json`
+- If the property is a `type: string` with `format: binary` or `format: base64` (aka a file object), the default Content-Type is `application/octet-stream`
+
+A different content-type may be defined in your api spec, but this is not yet supported in the code generation. Also, this "annotation-oriented" approach of RestEasy (i.e. using `@MultipartForm` to denote the multipart body parameter) does not seem to properly support the unmarshalling of arrays of the same type (e.g. array of files), in these cases it uses Content-Type equal to `application/json`.
+
+
 ## Generating files via InputStream
 
 Having the files in the `src/main/openapi` directory will generate the REST stubs by default. Alternatively, you can implement the `io.quarkiverse.openapi.generator.codegen.OpenApiSpecInputProvider`

deployment/src/main/java/io/quarkiverse/openapi/generator/deployment/SpecConfig.java

@@ -13,6 +13,7 @@ public class SpecConfig {
     public static final String MODEL_PKG_SUFFIX = ".model";
     public static final String BUILD_TIME_SPEC_PREFIX_FORMAT = BUILD_TIME_CONFIG_PREFIX + ".spec.\"%s\"";
     private static final String BASE_PACKAGE_PROP_FORMAT = "%s.base-package";
+    private static final String SKIP_FORM_MODEL_PROP_FORMAT = "%s.skip-form-model";
 
     /**
      * Defines the base package name for the generated classes.
@@ -32,6 +33,10 @@ public static String getResolvedBasePackageProperty(final Path openApiFilePath)
         return String.format(BASE_PACKAGE_PROP_FORMAT, getBuildTimeSpecPropertyPrefix(openApiFilePath));
     }
 
+    public static String getSkipFormModelPropertyName(final Path openApiFilePath) {
+        return String.format(SKIP_FORM_MODEL_PROP_FORMAT, getBuildTimeSpecPropertyPrefix(openApiFilePath));
+    }
+
     /**
      * Gets the config prefix for a given OpenAPI file in the path.
      * For example, given a path like /home/luke/projects/petstore.json, the returned value is

deployment/src/main/java/io/quarkiverse/openapi/generator/deployment/codegen/OpenApiGeneratorCodeGenBase.java

@@ -1,6 +1,7 @@
 package io.quarkiverse.openapi.generator.deployment.codegen;
 
 import static io.quarkiverse.openapi.generator.deployment.SpecConfig.getResolvedBasePackageProperty;
+import static io.quarkiverse.openapi.generator.deployment.SpecConfig.getSkipFormModelPropertyName;
 
 import java.io.IOException;
 import java.nio.file.Files;
@@ -62,6 +63,10 @@ protected void generate(CodeGenContext context, final Path openApiFilePath, fina
         context.config()
                 .getOptionalValue(getResolvedBasePackageProperty(openApiFilePath), String.class)
                 .ifPresent(generator::withBasePackage);
+        context.config()
+                .getOptionalValue(getSkipFormModelPropertyName(openApiFilePath), String.class)
+                .ifPresent(generator::withSkipFormModelConfig);
+
         generator.generate();
     }
 }

deployment/src/main/java/io/quarkiverse/openapi/generator/deployment/template/QuteTemplatingEngineAdapter.java

@@ -22,13 +22,13 @@ public class QuteTemplatingEngineAdapter extends AbstractTemplatingEngineAdapter
             "bodyParams.qute",
             "enumClass.qute",
             "enumOuterClass.qute",
-            "formParams.qute",
             "headerParams.qute",
             "pathParams.qute",
             "pojo.qute",
             "queryParams.qute",
             "auth/compositeAuthenticationProvider.qute",
-            "auth/authConfig.qute"
+            "auth/authConfig.qute",
+            "multipartFormdataPojo.qute"
     };
     public final Engine engine;
 

deployment/src/main/java/io/quarkiverse/openapi/generator/deployment/wrapper/OpenApiClientGeneratorWrapper.java

@@ -80,6 +80,17 @@ public OpenApiClientGeneratorWrapper withCircuitBreakerConfiguration(final Map<S
         return this;
     }
 
+    /**
+     * Sets the global 'skipFormModel' setting. If not set this setting will default to true.
+     *
+     * @param skipFormModel whether to skip the generation of models for form parameters
+     * @return this wrapper
+     */
+    public OpenApiClientGeneratorWrapper withSkipFormModelConfig(final String skipFormModel) {
+        GlobalSettings.setProperty(CodegenConstants.SKIP_FORM_MODEL, skipFormModel);
+        return this;
+    }
+
     public List<File> generate() {
         this.consolidatePackageNames();
         return generator.opts(configurator.toClientOptInput()).generate();

deployment/src/main/resources/templates/api.qute

@@ -58,7 +58,24 @@ public interface {classname} {
     @org.eclipse.microprofile.faulttolerance.CircuitBreaker
     {/if}{/for}
     {/if}{/for}
-    public {#if op.returnType}{op.returnType}{#else}void{/if} {op.nickname}({#for p in op.allParams}{#include pathParams.qute param=p/}{#include queryParams.qute param=p/}{#include bodyParams.qute param=p/}{#include formParams.qute param=p/}{#include headerParams.qute param=p/}{#if p_hasNext}, {/if}{/for});
+    public {#if op.returnType}{op.returnType}{#else}void{/if} {op.nickname}(
+        {#if op.hasFormParams}
+        @org.jboss.resteasy.annotations.providers.multipart.MultipartForm {op.operationIdCamelCase}MultipartForm multipartForm{#if op.hasPathParams},{/if}{!
+        !}{#for p in op.pathParams}{#include pathParams.qute param=p/}{#if p_hasNext}, {/if}{/for}{#if op.hasQueryParams},{/if}{!
+        !}{#for p in op.queryParams}{#include queryParams.qute param=p/}{#if p_hasNext}, {/if}{/for}{#if op.hasBodyParams},{/if}{!
+        !}{#for p in op.bodyParams}{#include bodyParams.qute param=p/}{#if p_hasNext}, {/if}{/for}{#if op.hasHeaderParams},{/if}{!
+        !}{#for p in op.headerParams}{#include headerParams.qute param=p/}{#if p_hasNext}, {/if}{/for}
+        {#else}
+        {#for p in op.allParams}
+        {#include pathParams.qute param=p/}{#include queryParams.qute param=p/}{#include bodyParams.qute param=p/}{#include headerParams.qute param=p/}{#if p_hasNext}, {/if}
+        {/for}
+        {/if}
+    );
+    {#if op.hasFormParams}
+
+    {#include multipartFormdataPojo.qute param=op/}
+    {/if}
+
 
     {/for}
 }

deployment/src/main/resources/templates/formParams.qute

@@ -0,0 +1,14 @@
+    public static class {op.operationIdCamelCase}MultipartForm {
+    {#for p in op.formParams}
+        @FormParam("{p.baseName}")
+    {#if p.isFile || (p.isString && p.dataFormat == 'base64')}
+        @org.jboss.resteasy.annotations.providers.multipart.PartFilename("{p.baseName}File")
+        @org.jboss.resteasy.annotations.providers.multipart.PartType(MediaType.APPLICATION_OCTET_STREAM)
+    {#else if p.isPrimitiveType or (p.isArray && p.items.isPrimitiveType)}
+        @org.jboss.resteasy.annotations.providers.multipart.PartType(MediaType.TEXT_PLAIN)
+    {#else}
+        @org.jboss.resteasy.annotations.providers.multipart.PartType(MediaType.APPLICATION_JSON)
+    {/if}
+        public {p.dataType} {p.paramName};
+    {/for}
+    }

deployment/src/main/resources/templates/multipartFormdataPojo.qute

@@ -13,58 +13,43 @@
 import java.nio.file.Paths;
 import java.util.List;
 import java.util.Map;
-import java.util.Objects;
 import java.util.Optional;
 
 import org.junit.jupiter.api.Test;
 
 import com.github.javaparser.StaticJavaParser;
 import com.github.javaparser.ast.CompilationUnit;
+import com.github.javaparser.ast.body.ClassOrInterfaceDeclaration;
 import com.github.javaparser.ast.body.EnumConstantDeclaration;
 import com.github.javaparser.ast.body.MethodDeclaration;
+import com.github.javaparser.ast.body.Parameter;
 
 public class OpenApiClientGeneratorWrapperTest {
 
     @Test
     void verifyCommonGenerated() throws URISyntaxException {
-        final Path petstoreOpenApi = Path
-                .of(requireNonNull(this.getClass().getResource("/openapi/petstore-openapi.json")).toURI());
-        final Path targetPath = Paths.get(getTargetDir(), "openapi-gen");
-        final OpenApiClientGeneratorWrapper generatorWrapper = new OpenApiClientGeneratorWrapper(petstoreOpenApi, targetPath);
-        final List<File> generatedFiles = generatorWrapper.generate();
+        final List<File> generatedFiles = createGeneratorWrapper("petstore-openapi.json").generate();
         assertNotNull(generatedFiles);
         assertFalse(generatedFiles.isEmpty());
     }
 
     @Test
     void verifyAuthBasicGenerated() throws URISyntaxException {
-        final Path petstoreOpenApi = Path
-                .of(requireNonNull(this.getClass().getResource("/openapi/petstore-openapi-httpbasic.json")).toURI());
-        final Path targetPath = Paths.get(getTargetDir(), "openapi-gen");
-        final OpenApiClientGeneratorWrapper generatorWrapper = new OpenApiClientGeneratorWrapper(petstoreOpenApi, targetPath);
-        final List<File> generatedFiles = generatorWrapper.generate();
+        final List<File> generatedFiles = createGeneratorWrapper("petstore-openapi-httpbasic.json").generate();
         assertTrue(generatedFiles.stream().anyMatch(f -> f.getName().equals("CompositeAuthenticationProvider.java")));
     }
 
     @Test
     void verifyAuthBearerGenerated() throws URISyntaxException {
-        final Path petstoreOpenApi = Path
-                .of(requireNonNull(this.getClass().getResource("/openapi/petstore-openapi-bearer.json")).toURI());
-        final Path targetPath = Paths.get(getTargetDir(), "openapi-gen");
-        final OpenApiClientGeneratorWrapper generatorWrapper = new OpenApiClientGeneratorWrapper(petstoreOpenApi, targetPath);
-        final List<File> generatedFiles = generatorWrapper.generate();
+        final List<File> generatedFiles = createGeneratorWrapper("petstore-openapi-bearer.json").generate();
         assertTrue(generatedFiles.stream().anyMatch(f -> f.getName().equals("CompositeAuthenticationProvider.java")));
     }
 
     @Test
     void verifyEnumGeneration() throws URISyntaxException, FileNotFoundException {
-        final Path issue28Path = Path
-                .of(requireNonNull(this.getClass().getResource("/openapi/issue-28.yaml")).toURI());
-        final Path targetPath = Paths.get(getTargetDir(), "openapi-gen");
-        final OpenApiClientGeneratorWrapper generatorWrapper = new OpenApiClientGeneratorWrapper(issue28Path, targetPath)
-                .withBasePackage("org.issue28");
-
-        final List<File> generatedFiles = generatorWrapper.generate();
+        final List<File> generatedFiles = createGeneratorWrapper("issue-28.yaml")
+                .withBasePackage("org.issue28")
+                .generate();
         final Optional<File> enumFile = generatedFiles.stream()
                 .filter(f -> f.getName().endsWith("ConnectorNamespaceState.java")).findFirst();
         assertThat(enumFile).isPresent();
@@ -114,15 +99,72 @@ void circuitBreaker() throws URISyntaxException, FileNotFoundException {
     }
 
     private List<File> generateRestClientFiles() throws URISyntaxException {
-        Path targetPath = Paths.get(getTargetDir(), "openapi-gen");
-
-        Path simpleOpenApiFile = Path.of(Objects.requireNonNull(getClass().getResource("/openapi/simple-openapi.json"))
-                .toURI());
-
-        OpenApiClientGeneratorWrapper generatorWrapper = new OpenApiClientGeneratorWrapper(simpleOpenApiFile, targetPath)
+        OpenApiClientGeneratorWrapper generatorWrapper = createGeneratorWrapper("simple-openapi.json")
                 .withCircuitBreakerConfiguration(Map.of(
                         "org.openapitools.client.api.DefaultApi", List.of("opThatDoesNotExist", "byeGet")));
 
         return generatorWrapper.generate();
     }
+
+    private OpenApiClientGeneratorWrapper createGeneratorWrapper(String specFileName) throws URISyntaxException {
+        final Path openApiSpec = Path
+                .of(requireNonNull(this.getClass().getResource(String.format("/openapi/%s", specFileName))).toURI());
+        final Path targetPath = Paths.get(getTargetDir(), "openapi-gen");
+
+        return new OpenApiClientGeneratorWrapper(openApiSpec, targetPath);
+    }
+
+    @Test
+    void verifyMultipartFormAnnotationIsGeneratedForParameter() throws URISyntaxException, FileNotFoundException {
+        List<File> generatedFiles = createGeneratorWrapper("multipart-openapi.yml")
+                .withSkipFormModelConfig("false")
+                .generate();
+        assertThat(generatedFiles).isNotEmpty();
+
+        Optional<File> file = generatedFiles.stream()
+                .filter(f -> f.getName().endsWith("UserProfileDataApi.java"))
+                .findAny();
+        assertThat(file).isPresent();
+
+        CompilationUnit compilationUnit = StaticJavaParser.parse(file.orElseThrow());
+        List<MethodDeclaration> methodDeclarations = compilationUnit.findAll(MethodDeclaration.class);
+        assertThat(methodDeclarations).isNotEmpty();
+
+        Optional<MethodDeclaration> multipartPostMethod = methodDeclarations.stream()
+                .filter(m -> m.getNameAsString().equals("postUserProfileData"))
+                .findAny();
+        assertThat(multipartPostMethod).isPresent();
+
+        List<Parameter> parameters = multipartPostMethod.orElseThrow().getParameters();
+        assertThat(parameters).hasSize(1);
+
+        Parameter param = parameters.get(0);
+        assertThat(param.getAnnotationByName("MultipartForm")).isPresent();
+    }
+
+    @Test
+    void verifyMultipartPojoGeneratedAndFieldsHaveAnnotations() throws URISyntaxException, FileNotFoundException {
+        List<File> generatedFiles = createGeneratorWrapper("multipart-openapi.yml")
+                .withSkipFormModelConfig("false")
+                .generate();
+        assertFalse(generatedFiles.isEmpty());
+
+        Optional<File> file = generatedFiles.stream()
+                .filter(f -> f.getName().endsWith("UserProfileDataApi.java"))
+                .findAny();
+        assertThat(file).isNotEmpty();
+
+        CompilationUnit compilationUnit = StaticJavaParser.parse(file.orElseThrow());
+        Optional<ClassOrInterfaceDeclaration> multipartPojo = compilationUnit.findAll(ClassOrInterfaceDeclaration.class)
+                .stream()
+                .filter(c -> c.getNameAsString().equals("PostUserProfileDataMultipartForm"))
+                .findAny();
+        assertThat(multipartPojo).isNotEmpty();
+
+        assertThat(multipartPojo.orElseThrow().getFields()).hasSize(3);
+        multipartPojo.orElseThrow().getFields().forEach(field -> {
+            assertThat(field.getAnnotationByName("FormParam")).isPresent();
+            assertThat(field.getAnnotationByName("PartType")).isPresent();
+        });
+    }
 }

deployment/src/test/java/io/quarkiverse/openapi/generator/deployment/wrapper/OpenApiClientGeneratorWrapperTest.java

@@ -0,0 +1,61 @@
+openapi: 3.0.3
+info:
+  title: "Multipart form data API"
+  description: An api that uses multipart/form-data as request type
+  version: 1.0.0
+
+servers:
+  - url: "http://my.endpoint.com/api/v1"
+
+paths:
+  /user-profile-data:
+    post:
+      tags:
+        - User Profile Data
+      description: Upload data for a user profile, adapted from https://swagger.io/docs/specification/describing-request-body/multipart-requests/
+      operationId: PostUserProfileData
+      requestBody:
+        required: true
+        description: The data of a user profile
+        content:
+          multipart/form-data:
+            schema:
+              $ref: '#/components/schemas/UserProfileData'
+      responses:
+        "204":
+          description: "Data uploaded"
+        "400":
+          description: "Invalid ID supplied"
+
+components:
+  schemas:
+    Address:
+      title: Address
+      type: object
+      properties:
+        street:
+          type: string
+          description: Street name
+          example: 7th avenue
+        city:
+          type: string
+          description: Name of the city
+          example: New Delhi
+    UserId:
+      type: string
+      format: uuid
+    ProfileImage:
+      type: string
+      format: binary
+
+    UserProfileData:
+      type: object
+      properties: # Request parts
+        id: # Part 1 (string value)
+          $ref: '#/components/schemas/UserId'
+        address: # Part2 (object)
+          $ref: '#/components/schemas/Address'
+        profileImage: # Part 3 (an image)
+          $ref: '#/components/schemas/ProfileImage'
+
+