Merge branch 'main' into dependabot/maven/quarkus.version-2.8.0.Final

Author: ricardozanini

.all-contributorsrc

@@ -21,7 +21,8 @@
       "avatar_url": "https://avatars.githubusercontent.com/u/11776454?v=4",
       "profile": "http://thegreatapi.com",
       "contributions": [
-        "doc"
+        "doc",
+        "code"
       ]
     },
     {
@@ -51,6 +52,15 @@
       "contributions": [
         "code"
       ]
+    },
+    {
+      "login": "Orbifoldt",
+      "name": "Orbifoldt",
+      "avatar_url": "https://avatars.githubusercontent.com/u/30009459?v=4",
+      "profile": "https://github.com/Orbifoldt",
+      "contributions": [
+        "code"
+      ]
     }
   ],
   "contributorsPerLine": 7,

README.md

@@ -1,7 +1,7 @@
 # Quarkus - OpenAPI Generator
 
 <!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section -->
-[![All Contributors](https://img.shields.io/badge/all_contributors-5-orange.svg?style=flat-square)](#contributors-)
+[![All Contributors](https://img.shields.io/badge/all_contributors-6-orange.svg?style=flat-square)](#contributors-)
 <!-- ALL-CONTRIBUTORS-BADGE:END -->
 
 Quarkus' extension for generation of [Rest Clients](https://quarkus.io/guides/rest-client) based on OpenAPI specification files.
@@ -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`
@@ -304,10 +367,11 @@ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/d
 <table>
   <tr>
     <td align="center"><a href="https://ricardozanini.medium.com/"><img src="https://avatars.githubusercontent.com/u/1538000?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Ricardo Zanini</b></sub></a><br /><a href="https://github.com/quarkiverse/quarkus-openapi-generator/commits?author=ricardozanini" title="Code">💻</a> <a href="#maintenance-ricardozanini" title="Maintenance">🚧</a></td>
-    <td align="center"><a href="http://thegreatapi.com"><img src="https://avatars.githubusercontent.com/u/11776454?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Helber Belmiro</b></sub></a><br /><a href="https://github.com/quarkiverse/quarkus-openapi-generator/commits?author=hbelmiro" title="Documentation">📖</a></td>
+    <td align="center"><a href="http://thegreatapi.com"><img src="https://avatars.githubusercontent.com/u/11776454?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Helber Belmiro</b></sub></a><br /><a href="https://github.com/quarkiverse/quarkus-openapi-generator/commits?author=hbelmiro" title="Documentation">📖</a> <a href="https://github.com/quarkiverse/quarkus-openapi-generator/commits?author=hbelmiro" title="Code">💻</a></td>
     <td align="center"><a href="http://gastaldi.wordpress.com"><img src="https://avatars.githubusercontent.com/u/54133?v=4?s=100" width="100px;" alt=""/><br /><sub><b>George Gastaldi</b></sub></a><br /><a href="https://github.com/quarkiverse/quarkus-openapi-generator/commits?author=gastaldi" title="Code">💻</a> <a href="#infra-gastaldi" title="Infrastructure (Hosting, Build-Tools, etc)">🚇</a></td>
     <td align="center"><a href="https://github.com/RishiKumarRay"><img src="https://avatars.githubusercontent.com/u/87641376?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Rishi Kumar Ray</b></sub></a><br /><a href="#infra-RishiKumarRay" title="Infrastructure (Hosting, Build-Tools, etc)">🚇</a></td>
     <td align="center"><a href="https://github.com/fjtirado"><img src="https://avatars.githubusercontent.com/u/65240126?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Francisco Javier Tirado Sarti</b></sub></a><br /><a href="https://github.com/quarkiverse/quarkus-openapi-generator/commits?author=fjtirado" title="Code">💻</a></td>
+    <td align="center"><a href="https://github.com/Orbifoldt"><img src="https://avatars.githubusercontent.com/u/30009459?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Orbifoldt</b></sub></a><br /><a href="https://github.com/quarkiverse/quarkus-openapi-generator/commits?author=Orbifoldt" title="Code">💻</a></td>
   </tr>
 </table>
 

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}
+    }