Hi Jean Pierre,
I suspect the @Multipart annotation is coming from CXF
(org.apache.cxf.jaxrs.ext.multipart.Multipart), right? If yes,
this is not a part of JAX-RS specification but CXF specific extension. You may
need to add Swagger API annotation to
the parameters in question:
@Parameter(schema = @Schema(type = "string", format = "binary"))
Hope it helps.
Thank you.
Best Regards,
Andriy Redko
Monday, July 1, 2024, 12:09:17 PM, you wrote:
> 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 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))),
> 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))
>
> }),
> @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-jaxrs2
> 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.
