Swagger UI 不支持为 RestEasy 正确上传文件

Question

我将 JAX-RS (RestEasy) 与 Swagger 一起使用。我的端点之一可以上传文件。上传文件的定义方式（在 RestEasy 中）是提供一个 org.jboss.resteasy.plugins.providers.multipart.MultipartFormDataInput 作为参数。

这是我的终点：

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

有什么问题？

不幸的是，swagger-ui 会根据 MultipartFormDataInput 的内部属性生成架构，而不是上传文件的按钮。我尝试使用 @FormParam 注释（以指示提供的参数应被解释为文件）以及 MultipartFormDataInput 参数，但应用程序不想编译。

问题：swagger中有没有solution/workaround提供上传文件的按钮-ui?

Answer 1

解决方案是从您的 apiFile 参数中删除 @ApiParam 并在方法上方添加 @ApiImplicitParam（未绑定到 Jax-RS 并允许手动定义参数）：

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

Answer 2

最终解决方案

最终解决方案包括一个选定的答案，但我们应该添加 @ApiParam(hidden = true) 而不是删除 @ApiParam。为什么？

如果我们删除@ApiParam，则有两个字段：apiId、body以及MultipartFormDataInput的内部属性和上传文件的按钮招摇-ui。这个 body 字段是一个副作用。要解决此问题，我们应该提供 @ApiParam(hidden = true)，然后在 swagger-ui.

中有带有 apiId 的字段和上传文件的按钮

顺便说一句：我在 1.5.12 版本中测试了下面的 swagger-ui 代码。

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

Swagger UI 不支持为 RestEasy 正确上传文件

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

multipartform-data

jax-rs

resteasy

swagger

swagger-ui

有什么问题？

最终解决方案