Add tests for encoding with multipart/form-data

[benjamin-confino]

Fixes #587

Depends on #616

For the comments there was mention of "Shall be ignored if not ... www-form-urlencoded or or multipart/form-data" in several places in the spec, but only one mention of "Shall be ignored if not ... www-form-urlencoded" in the current comments. I wasn't sure if I should only update the existing one or if I should add new ones too all. I decided there might be a good reason the other methods don't have that, but if you want them all say so and I'll add them.

[eclipse-microprofile-bot]

Can one of the admins verify this patch?

[Azquelt]

I wasn't sure if I should only update the existing one or if I should add new ones too all.

The javadoc is a little scatter-shot and inconsistent, so I'm also not sure whether there's a good reason that it's only mentioned in one place. I think your current change that just updates the information where we do have it is the right approach.

[Azquelt]

The name needs to be the name of a property included in the schema, see https://spec.openapis.org/oas/v3.1.0.html#media-type-object

Note that @Content corresponds to a Media Type Object.

[Azquelt]

Also, from the Encoding Object part of the spec:

style: ... This property SHALL be ignored if the request body media type is not application/x-www-form-urlencoded or multipart/form-data.
(similar text for explode and allowReserved)

I think this means these properties only make sense when applied to the content of a request body where its media type is multipart/form-data. (Which makes sense I think, multipart/form-data is a type sent by web browsers when the user submits a form).

Note that this is not the contentType of the @Content annotation, it's the value of @Consumes on the method.

Tbh, I'm not that familiar with receiving form data using Jakarta REST, I would probably start by looking up an example and then trying to add the OpenAPI documentation.

[Azquelt]

I had a look at this from the point of view of whether it's a valid resource method.

As far as I could find, there's no built-in support required for multipart/form-data in Jakarta REST 3.0 (EE 9). Support was only required in Jakarta REST 3.1 (EE 10).

However, in that case it would be treated as any other media type without built-in support and the Jakarta REST implementation would attempt to look up a MessageBodyReader and if one was not found, it would generate a NotSupportedException which could then be handled by an ExceptionHandler to generate a response.

Given this process, I think this method is a valid resource method, even if a compatible implementation may throw a NotSupportedException if the method was actually called.

Another option might be to use String or byte[] for which a built-in MessageBodyReader is required for all media types.

[Azquelt]

Ok, I think this looks good now. Ideally we would squash all the commits.

[Azquelt]

Squashed commits and removed merges.

[Azquelt]

@eclipse-microprofile-bot test this please