java - Swagger 文档 : description of the content of the response

Question

我有一个简单的 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 旁边，但我不确定此解决方案是否正确。

Answer 1

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

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