How does FileUpload work with OpenAPI?

[cristalp]

I've just updated to the latest Quarkus LTS version and now use quarkus-rest and its friends.

Can anyone explain in simple terms :-) how to use OpenAPI with this example: https://quarkus.io/guides/rest#multipart

With "use" I mean that I want an upload button in Swagger UI for the image file.

I see some bugs here, but I haven't managed to use FileUpload. I tried File, which showed the button but failed after uploading with Failed to decode URL.

[cristalp]

Please note that I'm away for the rest of the week, so please be patient :-)

[phillip-kruger]

@MikeEdgar - can you help ?

[MikeEdgar]

I'm away this week but I will take a look into this next week.

[MikeEdgar]

@cristalp , be sure to set @Consumes(MediaType.MULTIPART_FORM_DATA) on the multipart endpoint. The default application/x-www-form-urlencoded used for forms will not work.

[cristalp]

Ok, so this is what I get in OpenAPI:

From

@Path("multipart")
public class MultipartResource {
  public static class Person {
    public String firstName;
    public String lastName;
  }

  @POST
  public void multipart(@RestForm final String description,
            @RestForm("image") final FileUpload file,
            @RestForm @PartType(MediaType.APPLICATION_JSON) final Person person) {
        // do something
  }
}

I get

  /api/multipart:
    post:
      tags:
      - Multipart Resource
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                description:
                  type: string
                image:
                  $ref: "#/components/schemas/FileUpload"
                person:
                  $ref: "#/components/schemas/Person"
            encoding:
              person:
                contentType: application/json
      responses:
        "201":
          description: Created

I don't get an upload button for image.

Now, for the one with @Consumes

@Path("multipart")
public class MultipartResource {
  public static class Person {
    public String firstName;
    public String lastName;
  }

  @POST
  @Consumes(MediaType.MULTIPART_FORM_DATA)
  public void multipart(@RestForm final String description,
            @RestForm("image") final FileUpload file,
            @RestForm @PartType(MediaType.APPLICATION_JSON) final Person person) {
        // do something
  }
}

I get

  /api/multipart:
    post:
      tags:
      - Multipart Resource
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                description:
                  type: string
                image:
                  $ref: "#/components/schemas/FileUpload"
                person:
                  $ref: "#/components/schemas/Person"
            encoding:
              person:
                contentType: application/json
      responses:
        "201":
          description: Created

There still no upload button for image.

In both cases, FileUpload is defined like this:

    FileUpload:
      type: object

[cristalp]

I searched around some more and came up with this. Is this the right way to do it?

@Path("multipart")
public class MultipartResource {

  public static class Person {
    public String firstName;
    public String lastName;
  }

  @Schema(type = SchemaType.STRING, format = "binary")
  public static class UploadItemSchema {

  }

  @POST
  @Consumes(MediaType.MULTIPART_FORM_DATA)
  public void multipart(@RestForm final String description,
            @RestForm("image") @Schema(implementation = UploadItemSchema.class) final FileUpload file,
            @RestForm @PartType(MediaType.APPLICATION_JSON) final Person person) {
    System.out.println("description: " + description);
    System.out.println("person.firstName: " + person.firstName);
    System.out.println("person.lastName: " + person.lastName); //TODO remove System.out
    System.out.println("file.fileName: " + file.fileName());
    System.out.println("file.contentType: " + file.contentType());
    System.out.println("file.size: " + file.size());
  }
}

In OpenAPI:

  /api/multipart:
    post:
      tags:
      - Multipart Resource
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                description:
                  type: string
                image:
                  $ref: "#/components/schemas/UploadItemSchema"
                person:
                  $ref: "#/components/schemas/Person"
            encoding:
              person:
                contentType: application/json
      responses:
        "201":
          description: Created
...
    UploadItemSchema:
      format: binary
      type: string

It certainly works, see the output:

description: Something
person.firstName: John
person.lastName: Doe
file.fileName: foo.png
file.contentType: image/png
file.size: 206194

[MikeEdgar]

FileUpload should work out-of-the-box for recent Quarkus/smallrye-openapi versions. Do you know which versions you're using? Otherwise, that work-around is valid for versions not yet supporting FileUpload.

[cristalp]

I'm on 3.15.3, the most recent LTS version.

[MikeEdgar]

Ok, the LTS is using SmallRye 3.10 and the FileUpload support came in 3.11. You can continue using the work-around you posted or try using configuration if it is a more widespread issue in your app, to limit the number of changes.

mp.openapi.schema.org.jboss.resteasy.reactive.multipart.FileUpload={ "type": "string", "format": "binary" }

[cristalp]

Ok, thanks a lot for your help!