Swagger文档：响应内容的描述

Question

我有一个简单的 fileUpload rest API，它将上传的文件存储在数据库中，returns 将上传文件的唯一引用存储在数据库中 (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)

Swagger文档：响应内容的描述

Swagger documentation: description of the content of the response

java

jax-rs

jersey

swagger