Swagger документация: описание содержания ответа - PullRequest
Новая
       43

Swagger документация: описание содержания ответа

0 голосов
/ 12 июня 2018

У меня есть простой API fileUpload rest, который сохраняет загруженный файл в базе данных и возвращает с уникальной ссылкой на загруженный файл в базе данных (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, но я не уверен, правильно ли это решение.

1 Ответ

0 голосов
/ 12 июня 2018

Исходя из моего опыта со сваггером, я думаю, что это должно быть указано в поле примечаний в ApiOperation, как показано ниже 

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