如何配置Swagger UI、Jersey和文件上传？

Question

我有一个Jersey服务，其文件上载方法如下（简化）：

@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...
}

它可以工作，我可以在Chrome中使用Postman扩展成功地测试它。

但是，Swagger看到两个名为“file”的参数。不知何故，它似乎理解了InputStream参数和FormDataContentDisposition参数实际上是同一文件参数的两个部分，但对于formdataodypart参数，它看不到这一点。

这是Swagger JSON的参数：

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
}]

因此，Swagger UI为FormDataCodePart参数生成一个文件选择器字段和一个额外的文本字段：

因此，当我选择一个文件并在Swagger UI中提交表单时，我最终会读取InputStream中文本字段的内容，而不是上传文件的内容。如果我将文本字段留空，我将得到文件的名称。

如何指示Swagger忽略FormDataCodePart参数？

或者，作为一种解决方法，在没有FormDataCodePart对象的情况下，如何获取上载文件的媒体类型？

我使用Jersey 2.7和swagger-Jersey 2-jaxrs_2.10版本1.3.4。

Answer 1

不清楚这是什么时候添加到Jersey的，但在Multipart部分末尾的一个注释中说“@FormDataParam注释也可以用于字段”。果然，您可以做到这一点：

@FormDataParam(value="file") FormDataContentDisposition fileDisposition;
@FormDataParam("fileBodyPart") FormDataBodyPart body;

@Path("/v1/source")
@POST
@Consumes(MediaType.MULTIPART_FORM_DATA)
@Produces({ MediaType.APPLICATION_JSON})
@ApiOperation(
        value = "Create a new Source from an uploaded file.",
        response = Source.class
        )
public Response makeSource(
        @FormDataParam(value="file") InputStream inputStream
        )
{
    logger.info(fileDisposition.toString());
    return makeSourceRaw(inputStream, fileDisposition.getFileName());
}

这提供了FormDataContentDisplace，但使它对Swagger不可见。

更新：这是可行的，但如果有其他定义的资源（@Path注释）不采用FormDataContentDisplace。如果有，那么泽西岛在运行时失败，因为它不能填写fileDisplace字段。

如果您使用Swagger的最新版本将参数简单地标记为隐藏，这是一个更好的解决方案。

@FormDataParam("fileBodyPart") FormDataBodyPart body;

@Path("/v1/source")
@POST
@Consumes(MediaType.MULTIPART_FORM_DATA)
@Produces({ MediaType.APPLICATION_JSON})
@ApiOperation(
        value = "Create a new Source from an uploaded file.",
        response = Source.class
        )
public Response makeSource(
        @FormDataParam(value="file") InputStream inputStream,
        @ApiParam(hidden=true) @FormDataParam(value="file") FormDataContentDisposition fileDisposition;

        )
{
    logger.info(fileDisposition.toString());
    return makeSourceRaw(inputStream, fileDisposition.getFileName());
}

Answer 2

为jersey创建一个招摇过市过滤器，然后将参数标记为internal或其他要过滤的字符串。此示例中也显示了这一点：

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

您的服务方法将具有此参数注释

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

您的筛选器将按如下方式查找它：

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;
}

注册新泽西的swagger过滤器，然后它将不会返回该字段，swagger-ui也不会显示它，这将解决您的上传问题。

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