How to configure Swagger UI, Jersey and file upload?

java, jersey, rest, swagger, swagger-ui

Solution

Create a swagger filter for jersey and then mark the parameter as internal or some other string you are filtering on. This is also shown in this example:

https://github.com/wordnik/swagger-core/blob/master/samples/java-jaxrs/src/main/java/com/wordnik/swagger/sample/util/ApiAuthorizationFilterImpl.java

Your service method will have this parameter annotation

@ApiParam(access = "internal") @FormDataParam("file") FormDataBodyPart body,

Your filter will look for it like this:

public boolean isParamAllowed(Parameter parameter, Operation operation, ApiDescription api,
        Map<String, List<String>> params, Map<String, String> cookies, Map<String, List<String>> headers) {
    if ((parameter.paramAccess().isDefined() && parameter.paramAccess().get().equals("internal")))
        return false;
    else
        return true;
}

Register your swagger filter for jersey and then it will not return that field and swagger-ui will not show it which will fix your upload problem.

<init-param>
      <param-name>swagger.filter</param-name>
      <param-value>your.company.package.ApiAuthorizationFilterImpl</param-value>
    </init-param>

Problem

I have a Jersey service with a file upload method that looks like this (simplified): ``` @POST @Path("/{observationId : [a-zA-Z0-9_]+}/files") @Produces({ MediaType.APPLICATION_JSON}) @Consumes(MediaType.MULTIPART_FORM_DATA) @ApiOperation( value = "Add a file to an observation", notes = "Adds a file to an observation and returns a JSON representation of the uploaded file.", response = ObservationMediaFile.class ) @ApiResponses({ @ApiResponse(code = 404, message = "Observation not found. Invalid observation ID."), @ApiResponse(code = 406, message= "The media type of the uploaded file is not supported. Currently supported types are 'images/*' where '*' can be 'jpeg', 'gif', 'png' or 'tiff',") }) public RestResponse<ObservationMediaFile> addFileToObservation( @PathParam("observationId") Long observationId, @FormDataParam("file") InputStream is, @FormDataParam("file") FormDataContentDisposition fileDetail, @FormDataParam("fileBodyPart") FormDataBodyPart body ){ MediaType type = body.getMediaType(); //Validate the media type of the uploaded file... if( /* validate it is an image */ ){ throw new NotAcceptableException("Not an image. Get out."); } //do something with the content of the file try{ byte[] bytes = IOUtils.toByteArray(is); }catch(IOException e){} //return response... } ``` It works and I can test it successfully using Postman extension in Chrome. However, Swagger sees 2 parameters named "file". Somehow it seems to understand that the `InputStream` parameter and the `FormDataContentDisposition` parameter are actually 2 parts of the same `file` parameter, but it fails to see that for the `FormDataBodyPart` parameter. This is the Swagger JSON for the parameters : ``` parameters: [ { name: "observationId", required: true, type: "integer", format: "int64", paramType: "path", allowMultiple: false }, { name: "file", required: false, type: "File", paramType: "body", allowMultiple: false }, { name: "fileBodyPart", required: false, type: "FormDataBodyPart", paramType: "form", allowMultiple: false }] ``` As a result, Swagger UI generates a file picker field, and an extra text field for the FormDataBodyPart argument : So when I pick a file and submit the form in Swagger UI, I end up reading the content of the text field in the InputStream instead of the content of the uploaded file. And if I leave the textfield empty, I get the name of the file. How can I instruct Swagger to ignore the FormDataBodyPart parameter ? Alternatively, as a work-around, how can I obtain the media type of the uploaded file without the FormDataBodyPart object ? I use Jersey 2.7 and swagger-jersey2-jaxrs_2.10 version 1.3.4.

Original source