Cannot generate MultipartForm server-side API

[mcruzdev]

This issue is related to quarkiverse/quarkus-openapi-generator#1154 issue.

For Quarkus , we need to following this tutorial here https://quarkus.io/guides/rest#multipart.

When the user uses by example:

{
  "openapi": "3.0.3",
  "info": {
    "title": "File Upload API",
    "version": "1.0.0"
  },
  "paths": {
    "/mypath": {
      "post": {
        "operationId": "mymethod",
        "summary": "Upload two files and receive a PDF response",
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "$ref": "#/components/schemas/FileUploadForm"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/pdf": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "FileUploadForm": {
        "type": "object",
        "properties": {
          "file1": {
            "type": "string",
            "format": "binary"
          },
          "file2": {
            "type": "string",
            "format": "binary"
          }
        },
        "required": ["file1", "file2"]
      }
    }
  }
}

The resource should have the following contract:

package org.example.api;

import jakarta.validation.constraints.NotNull;
import jakarta.ws.rs.Consumes;
import jakarta.ws.rs.POST;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.Response;
import org.eclipse.microprofile.openapi.annotations.Operation;
import org.example.api.beans.FileUploadForm;
import org.jboss.resteasy.annotations.providers.multipart.MultipartForm;

/**
 * A JAX-RS interface. An implementation of this interface must be provided.
 */
@Path("/mypath")
public interface MypathResource {
  @Operation(summary = "Upload two files and receive a PDF response", operationId = "mymethod")
  @POST
  @Produces("application/pdf")
  @Consumes("multipart/form-data")
  Response mymethod(@MultipartForm @NotNull FileUploadForm data);
}

And the bean, something like it:

import import org.jboss.resteasy.reactive.multipart.FileUpload;

public class FileUploadForm {
    private FileUpload file1;
    private FileUpload file2;
}

Another point: When the user uses a inline object with binary no bean are created and instead it a InputStream is added as body:

          multipart/form-data:
            schema:
              type: object
              properties:
                file1:
                  type: string
                  format: binary
                file2:
                  type: string
                  format: binary

cc: @EricWittmann @lpieprzyk @luca-vercelli @CodingLenni

[EricWittmann]

We probably need special handling of multipart/form-data in the code generator. I think InputStream is often a reasonable choice for binary inputs, but certainly not always.

[luca-vercelli]

a reasonable choice

Well, no, I do not agree. InputStream is too broad to handle. Imagine you have uploaded 10 files... and server side you have all them mixed up in a single InputStream...

[lpieprzyk]

a reasonable choice

Well, no, I do not agree. InputStream is too broad to handle. Imagine you have uploaded 10 files... and server side you have all them mixed up in a single InputStream...

I am with @luca-vercelli on this. However, wouldn't it be possible to take the Bean generation with FileUpload as a default and with a config param the current InputStream is generated?

[EricWittmann]

Sorry, what I meant was that InputStream is a reasonable choice in other use-cases. For example, we have an API in apicurio where the request body can be any type of raw file. So InputStream is the type used for the JAX-RS method param.

In this case (form-data), I agree that it doesn't work. That said, I suppose it's jsonschema2pojo that is generating the InputStream types in the generated code?

This is why I say that form-data might need to have special handing in the code generator.

[lpieprzyk]

Sorry, what I meant was that InputStream is a reasonable choice in other use-cases. For example, we have an API in apicurio where the request body can be any type of raw file. So InputStream is the type used for the JAX-RS method param.

In this case (form-data), I agree that it doesn't work. That said, I suppose it's jsonschema2pojo that is generating the InputStream types in the generated code?

This is why I say that form-data might need to have special handing in the code generator.

@mcruzdev asked If I could implement this one. Could you please give me a brief summary of this repo and where the right place for this special handling would be.

[EricWittmann]

OK. Well, the general approach here is that we parse an OpenAPI file into an AST using apicurio-data-models. Then we visit that AST and produce a new AST specific for Java code generation. Start here:

https://github.com/Apicurio/apicurio-codegen/blob/main/core/src/main/java/io/apicurio/hub/api/codegen/OpenApi2JaxRs.java

Here is where we generate the Java beans from the defined data types:

https://github.com/Apicurio/apicurio-codegen/blob/main/core/src/main/java/io/apicurio/hub/api/codegen/OpenApi2JaxRs.java#L318-L323

That is for schemas defined in the components/schema section of the spec. I don't think the code generator currently supports generating beans from inline schemas.

Note that java beans are generated from schemas by a third party library called jsonschema2pojo.

I suspect that we would need to detect that a schema is a multipart/formdata type and if it is NOT generate a bean using jsonschema2pojo (unless that library can be configured to generate what we want).

[mcruzdev]

@EricWittmann thanks a lot for the introduction.

@lpieprzyk do you need a help to solve this one?

[lpieprzyk]

@EricWittmann thanks a lot for the introduction.

@lpieprzyk do you need a help to solve this one?

@mcruzdev Unfortunately, I haven’t had the time to look into it yet, but I hope to do so in the next two weeks.

[mcruzdev]

@EricWittmann thanks a lot for the introduction.

@lpieprzyk do you need a help to solve this one?

@mcruzdev Unfortunately, I haven’t had the time to look into it yet, but I hope to do so in the next two weeks.

Take your time, no worry!

[lpieprzyk]

@mcruzdev About the contract you mentioned in your opening comment -
Wouldn't the right contract look somehting like this:

import org.jboss.resteasy.reactive.RestForm;
import org.jboss.resteasy.reactive.multipart.FileUpload;
// [...] other imports

/**
 * A JAX-RS interface. An implementation of this interface must be provided.
 */
@Path("/mypath")
public interface MypathResource {

  @Path("/myMethod")
  @Operation(summary = "Upload two files and receive a PDF response", operationId = "mymethod")
  @POST
  @Produces("application/pdf")
  @Consumes("multipart/form-data")
  Response mymethod(@RestForm("file")  @NotNull FileUploadForm data);
  }

[lpieprzyk]

@mcruzdev I have another question: I did some testing with different YAML's and services, but ran into some problems.
Doesn't the quarkiverse/quarkus-openapi-generator support the generation different server stub on the basis of mulitple specifications?

[mcruzdev]

@mcruzdev About the contract you mentioned in your opening comment -
Wouldn't the right contract look somehting like this:

Yes @lpieprzyk, you added the right method signature. https://quarkus.io/guides/rest#multipart

@mcruzdev I have another question: I did some testing with different YAML's and services, but ran into some problems.
Doesn't the quarkiverse/quarkus-openapi-generator support the generation different server stub on the basis of mulitple specifications?

Only the client extension does it, the server extension does not generate looking mulitple files (we need to support this one too).

[charlie-wolle]

@mcruzdev @lpieprzyk What is the current status? Is there a roadmap?

[mcruzdev]

Hello @lpieprzyk, are you mind to complete this issue? If not I can take care about it.