Swagger 文档：响应内容的描述答案

【问题标题】：Swagger documentation: description of the content of the responseSwagger 文档：响应内容的描述
【发布时间】：2018-06-12 17:43:52
【问题描述】：

我有一个简单的fileUpload rest API，它将上传的文件存储在数据库中，并返回数据库中上传文件的唯一引用（uuid）。

我使用 swagger 来生成 API 文档，它就像一个魅力，但我找不到添加描述文本来描述响应内容的方法。

这是我的 REST 的签名：

@POST
@Path("/upload")
@Consumes(ExtendedMediaType.MULTIPART_FORM_DATA)
@ApiOperation(
        value = "Save an image",
        notes = "Save the uploaded image to database.",
        response = String.class)
@ApiResponses(value = {
        @ApiResponse(code = 200, message = "The uploaded image has been saved.", response = String.class),
        @ApiResponse(code = 500, message = "Error while trying to resize the image.<p>Internal error code: 2103", response = a.b.ErrorInfo.class)})
@Override
public String uploadImage(
        @ApiParam(value = "file to upload", required = true) @FormDataParam("file") final InputStream inputStream,
        @ApiParam(value = "details of the uploaded file", required = true) @FormDataParam("file") final FormDataContentDisposition fileDetail) {

    //return UUID.randomUUID().toString();
}

我想在 API 文档中添加以下信息，以便描述响应字符串的内容：

"The unique id of the uploaded image."

我查看了ApiResponses 文档，但没有找到与此主题相关的任何内容。

我可以将此信息放在ApiResponse HTTP 200 旁边，但我不确定此解决方案是否正确。

【问题讨论】：

标签： java jersey jax-rs swagger

【解决方案1】：

根据我对 swagger 的经验，我认为它必须在 ApiOperation 的注释字段中指定，如下所示

@ApiOperation(
        value = "Save an image",
        notes = "Returns the unique id of the uploaded image",
        response = String.class)

【讨论】：