Swagger UI doesn't support uploading a file properly for RestEasy

Question

I use a JAX-RS (RestEasy) along with a Swagger. One of my endpoint can upload a file. Defined way to upload the file (in RestEasy) is to provide a org.jboss.resteasy.plugins.providers.multipart.MultipartFormDataInput as a parameter.

Here is my endpoint:

@PUT
@Path("/apis/{id}/file")
@Consumes(MediaType.MULTIPART_FORM_DATA)
@Produces(MediaType.APPLICATION_JSON)
@ApiOperation(value = "Registers a file.", code = 201, nickname = "registerFile")
@ApiResponses(
    value = {
        @ApiResponse(code = 201, message = "File created.",
                     response = FileCreated.class),
        @ApiResponse(code = 400, message = "Invalid parameters."),
        @ApiResponse(code = 404, message = "API is not found.")})
Response registerFile(
    @ApiParam(value = "API ID.", required = true) @PathParam("id") String apiId,
    @ApiParam(value = "File to register.", required = true, type = "file", name = "apiFile")
        MultipartFormDataInput apiFile) throws AppException;

What is the problem?

Unfortunately, swagger-ui generates a schema based on the inner properties of the MultipartFormDataInput instead of a button to upload the file. I tried use a @FormParam annotation (to indicate that the providing parameter should be interpreted as file) along with the MultipartFormDataInput parameter, but then the app doesn't want to compile.

Question: Is there any solution/workaround to provide the button to upload the file in the swagger-ui?

Answer 1

The solution is removing @ApiParam from your apiFile argument and adding @ApiImplicitParam (which is not bound to Jax-RS and allows defining parameters manually) above the method :

@ApiImplicitParams({@ApiImplicitParam (value = "File to register.", required = true, dataType = "file", name = "apiFile", paramType="formData")})

Answer 2

The final solution

The final solution includes a selected answer, but instead of removing @ApiParam we should add @ApiParam(hidden = true). Why?

If we remove @ApiParam, there are two fields: apiId, body with the inner properties of the MultipartFormDataInput and the button to upload the file in the swagger-ui. This body field is a side effect. To fix this issue we should provide @ApiParam(hidden = true), then there are the field with apiId and the button to upload the file in the swagger-ui.

BTW: I tested below code for swagger-ui in 1.5.12 version.

@PUT
@Path("/apis/{id}/file")
@Consumes(MediaType.MULTIPART_FORM_DATA)
@Produces(MediaType.APPLICATION_JSON)
@ApiOperation(value = "Registers a file.", code = 201, nickname = "registerFile")
@ApiResponses(
    value = {
        @ApiResponse(code = 201, message = "File created.",
                     response = FileCreated.class),
        @ApiResponse(code = 400, message = "Invalid parameters."),
        @ApiResponse(code = 404, message = "API is not found.")})
@ApiImplicitParams(
    @ApiImplicitParam(value = "File to register.", required = true, dataType = "file", 
                      name = "apiFile", paramType = "formData"))
Response registerFile(
    @ApiParam(value = "API ID.", required = true) @PathParam("id") String apiId,
    @ApiParam(hidden = true) MultipartFormDataInput apiFile) throws AppException;