Hi all,
I am having problems to correctly annotate service methods which consumes
multipart/form-data that contains attachments next to other model objects.
I’ve an openapi specification that contains following requestBody
definition:
/messages:
post:
tags:
- "messages"
summary: "Send a message, using a channel (email, paper mail,
ebox) and delivery method (registered or normal) of your choice.
More than
6 upfiles only supported for PAPER delivery."
operationId: createMessage
parameters:
- $ref: '#/components/parameters/CorrelationId'
- $ref: '#/components/parameters/Idempotency-Key'
* requestBody*:
content:
multipart/form-data:
schema:
type: object
required:
- messageToSend
properties:
messageToSend:
$ref: '#/components/schemas/MessageToSend'
upfile1:
type: string
format: binary
nullable: true
upfile2:
type: string
format: binary
nullable: true
upfile3:
type: string
format: binary
nullable: true
upfile4:
type: string
format: binary
nullable: true
upfile5:
type: string
format: binary
nullable: true
upfile6:
type: string
format: binary
nullable: true
upfile7:
type: string
format: binary
nullable: true
upfile8:
type: string
format: binary
nullable: true
upfile9:
type: string
format: binary
nullable: true
upfile10:
type: string
format: binary
nullable: true
upfile11:
type: string
format: binary
nullable: true
upfile12:
type: string
format: binary
nullable: true
upfile13:
type: string
format: binary
nullable: true
upfile14:
type: string
format: binary
nullable: true
upfile15:
type: string
format: binary
nullable: true
upfile16:
type: string
format: binary
nullable: true
upfile17:
type: string
format: binary
nullable: true
upfile18:
type: string
format: binary
nullable: true
upfile19:
type: string
format: binary
nullable: true
upfile20:
type: string
format: binary
nullable: true
qrfile:
type: string
format: binary
nullable: true
required: true
When using the *openapi-generator-maven-plugin*
<https://openapi-generator.tech/docs/plugins/> v7.6.0 it generates
following method signature:
@POST
@Path("/messages")
@Consumes("multipart/form-data")
@Produces({ "application/json" })
@Operation(
summary = "Send a message, using a channel
(email, paper mail, ebox) and delivery method (registered or normal) of
your choice. More than 6 upfiles only supported for PAPER delivery.",
tags = {"messages" },
operationId="createMessage",
security=@SecurityRequirement(name=
"BearerAuthentication"),
responses= {
@ApiResponse(
responseCode =
"201",
description =
"Created",
content =
@Content(mediaType=MediaType.*APPLICATION_JSON*,array=@ArraySchema(
*schema=@Schema(implementation=SendStatusMessage.**class**))*
<schema=@Schema(implementation=SendStatusMessage.class))>),
headers = {
@Header(
name="X-Magda-Exceptions",
required=*false*,
description="Only used in the
context of EBOX delivery and if there was a problem with the
consent of the
receiver's ebox.",
*schema=@Schema(implementation=MagdaExceptionList.**class**)*
<schema=@Schema(implementation=MagdaExceptionList.class)>)
}),
@ApiResponse(
responseCode =
"400",
description = "Invalid
data supplied",
content =
@Content(mediaType=MediaType.*APPLICATION_JSON*,schema=@Schema
(implementation=ErrorMessage.*class*))),
@ApiResponse(
responseCode =
"401",
description = "Invalid
authorization",
content =
@Content(mediaType=MediaType.*APPLICATION_JSON*,schema=@Schema
(implementation=ErrorMessage.*class*))),
@ApiResponse(
responseCode =
"500",
description = "Unexpected
Server Error",
content =
@Content(mediaType=MediaType.*APPLICATION_JSON*,schema=@Schema
(implementation=ErrorMessage.*class*))),
@ApiResponse(
responseCode =
"502",
description = "Bad
Gateway",
content =
@Content(mediaType=MediaType.*APPLICATION_JSON*,schema=@Schema
(implementation=ErrorMessage.*class*))),
@ApiResponse(
responseCode =
"503",
description = "Service
unavailable",
content =
@Content(mediaType=MediaType.*APPLICATION_JSON*,schema=@Schema
(implementation=ErrorMessage.*class*))),
@ApiResponse(
responseCode =
"504",
description = "Gateway
Timeout",
content =
@Content(mediaType=MediaType.*APPLICATION_JSON*,schema=@Schema
(implementation=ErrorMessage.*class*)))
})
* public* Response* createMessage*(
@HeaderParam("x-correlation-id") @NotNull
@Size(min = 10, max = 36) @Parameter(description="ID of the
transaction. Use this ID for log tracing and incident handling.")
String xCorrelationId,
@HeaderParam("Idempotency-Key") @Size(min = 10,
max = 36) @Parameter(description="When retrying a failed call, the
retry call should have the same Idempotency Key.") String
idempotencyKey,
@Multipart(value = "messageToSend”, required=*
true*) MessageToSend messageToSend,
@Multipart(value = "upfile1", required =*
false*) Attachment upfile1Detail,
@Multipart(value = "upfile2", required =*
false*) Attachment upfile2Detail,
@Multipart(value = "upfile3", required =*
false*) Attachment upfile3Detail,
@Multipart(value = "upfile4", required =*
false*) Attachment upfile4Detail,
@Multipart(value = "upfile5", required =*
false*) Attachment upfile5Detail,
@Multipart(value = "upfile6", required =*
false*) Attachment upfile6Detail,
@Multipart(value = "upfile7", required =*
false*) Attachment upfile7Detail,
@Multipart(value = "upfile8", required =*
false*) Attachment upfile8Detail,
@Multipart(value = "upfile9", required =*
false*) Attachment upfile9Detail,
@Multipart(value = "upfile10", required =*
false*) Attachment upfile10Detail,
@Multipart(value = "upfile11", required =*
false*) Attachment upfile11Detail,
@Multipart(value = "upfile12", required =*
false*) Attachment upfile12Detail,
@Multipart(value = "upfile13", required =*
false*) Attachment upfile13Detail,
@Multipart(value = "upfile14", required =*
false*) Attachment upfile14Detail,
@Multipart(value = "upfile15", required =*
false*) Attachment upfile15Detail,
@Multipart(value = "upfile16", required =*
false*) Attachment upfile16Detail,
@Multipart(value = "upfile17", required =*
false*) Attachment upfile17Detail,
@Multipart(value = "upfile18", required =*
false*) Attachment upfile18Detail,
@Multipart(value = "upfile19", required =*
false*) Attachment upfile19Detail,
@Multipart(value = "upfile20", required =*
false*) Attachment upfile20Detail,
@Multipart(value = "qrfile", required =*
false*) Attachment qrfileDetail);
If I now generate the swagger from this code (I modified the annotations in
the generated code for using OAS v3 annotations through* swagger-jaxrs**2**
v2.1.13* and I am using* cxf-v3.5.6* having* swagger-ui v4.18.2* generate
the user interface) none of the upload files appears as request parameter,
only the messageToSend is shown.
Is the above signature for the method createMessage(...) incorrect?
If I look at the generated openapi.json all the Attachment upFiles are
missing from the specification? So is it a problem/short-coming(?) of the
used software libraries, which then:
· cxf-rt-rs-service-description-common-openapi v3.5.6 -> this
library references swagger-jaxrs2 v2.1.13
· swagger-jaxrs2 v2.1.13 ->
can I upgradethis to e.g. swagger-jaxrs2 v2.2.22 (latest) while retaining
cxf v3.5.6?
· ...another?
Regards,
J.P.
