[jaxrs-spec] Bind an array of binary form properties to a list

Draft
IG
3mo ago
+51-1

A type: array of format: binary form properties was collapsed onto the scalar file type, so a multi-file upload was generated with the same signature as a single-file one — only the array dimension was silently dropped, and only one file could ever be bound.

Given:

files:
  type: array
  items:
    type: string
    format: binary

Before (identical to the single-file signature):

public Response uploadMultiple(@FormParam(value = "files") InputStream filesInputStream) {

After — default library:

public Response uploadMultiple(@FormParam(value = "files") List<InputStream> filesInputStream) {

After — quarkus library:

public Response uploadMultiple(@RestForm(value = "files") List<FileUpload> files) {

The array dimension is now preserved. isArray was already populated on file parameters — this mirrors what JavaJaxRS/libraries/jersey3 already does with List<FormDataBodyPart> — so no DefaultCodegen change was needed.

The quarkus library additionally moves from InputStream to the RESTEasy Reactive multipart types via a new library-scoped formParams.mustache. Per the Quarkus REST guide, the supported multipart types are FileUpload, Path, File, byte[] and Buffer; InputStream is not among them, and multiple files sharing one part name require List<FileUpload>. The other libraries (thorntail, helidon, openliberty, kumuluzee, default) keep plain java.io/java.util types so nothing outside Quarkus gains a dependency.

The org.jboss.resteasy.reactive imports are emitted only for API files that actually declare a file form parameter, via a new hasFileFormParams flag — verified against petstore, where only PetApi gets them and StoreApi/UserApi stay unchanged.

Note this changes the generated signature for existing quarkus users with a single-file upload: InputStream _fileInputStream becomes FileUpload _file. That is the type Quarkus actually supports, but it is a breaking change for code implementing the generated interfaces.

Testing

  • 3 new tests in JavaJAXRSSpecServerCodegenTest (array-as-list for the default library, List<FileUpload> for quarkus, and an import-gating regression test); reuses the existing 3_0/form-multipart-binary-array.yaml fixture.
  • 151 tests in JavaJAXRSSpecServerCodegenTest and 1084 across org.openapitools.codegen.java.** pass.
  • The regenerated samples/server/petstore/jaxrs-spec-quarkus-mutiny sample compiles against Quarkus (mvn compile), and a live Quarkus app built from these templates bound 3 files posted under one part name.

PR checklist

  • Read the contribution guidelines.
  • Run the following to build the project and update samples: 
    ./mvnw clean package || exit
./bin/generate-samples.sh ./bin/configs/*.yaml || exit
./bin/utils/export_docs_generators.sh || exit
    (For Windows users, please run the script in WSL)
    Commit all changed files.
    This is important, as CI jobs will verify all generator outputs of your HEAD commit as it would merge with master.
    These must match the expectations made by your contribution.
    You may regenerate an individual generator by passing the relevant config(s) as an argument to the script, for example ./bin/generate-samples.sh bin/configs/java*.
    IMPORTANT: Do NOT purge/delete any folders/files (e.g. tests) when regenerating the samples as manually written tests may be removed.
  • If your PR is targeting a particular programming language, @mention the technical committee members, so they are more likely to review the pull request.

Summary by cubic

Fixes multi-file form uploads in jaxrs-spec by preserving array dimensions for format: binary. Arrays of files now bind to @FormParam List<InputStream> instead of collapsing to a single InputStream.

  • Bug Fixes
    • Arrays of binary form parts now generate @FormParam("...") List<InputStream> ...InputStream.
    • Single-file params stay as InputStream; existing signatures are unchanged.
    • Applies to all libraries, including quarkus.