CODEWITHSUNDEEP
javajerseyjax-rsswagger
zappee
zappee

Reputation: 22668

Swagger documentation: description of the content of the response

I have a simple fileUpload rest API which stores the uploaded file in database and returns with the unuque reference of the uploaded file in the database (uuid).

I use swagger to generate API documentation and it works like a charm but I can not find a way to add description text to describe the content of the response.

This is the signature of my 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();
}

I would like to add the following info to the API documentation in order to describe the content of the response string:

"The unique id of the uploaded image."

I have checked the ApiResponses documentation but I have not found anything related to this topic.

I can put this info next to the ApiResponse HTTP 200 but I am not sure whether this solution is correct or not.

Upvotes: 1

Views: 792

Answers (1)

Aarish Ramesh
Aarish Ramesh

Reputation: 7023

From my experience with swagger, I think it must be specified in the notes field in the ApiOperation like below

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

Upvotes: 2

Related Questions