Show XML/JSON sample value in Swagger UI using swagger's annotations

Question

I am implementing Jersey based REST API and using swagger to generate HTML based documentation for the same. I am using swagger's annotations to read and scan the resources to generate documentation. I have specified response for each resource using @ApiResponse annotation as below:

@Path("/hello")
@Api(value = "Hello World" )
public class HelloRest
{
    @GET
    @ApiOperation(value="Hello world", httpMethod="GET")
    @ApiResponses(value={ @ApiResponse(code = 200, message = "Success", response = WebservicesErrorResponse.class, reference = "C:/Desktop/hello.json")
                          @ApiResponse(code = 404, message = "Not found", response = WebservicesErrorResponse.class)})
    @Produces({"application/json", "application/xml"})
    public Response helloWorld() 
    {
        return Response.status(WebservicesCommonTypes.SUCCESS).entity("Hello rest API").build();
    }
}

It is working fine and it is generating HTML based documentation as below:

As it shows the complete structure (Model and example value) of response if response code is 404. And in example value, it is not showing the values, only showing the type for each parameter for the model.

I want to show the sample example schema for the response so that client can understand that what would be the exact response for each response. I researched on it and I found that there is one attribute:

@ApiResponse(reference = "") - Specifies a reference to the response type. The specified reference can be either local or remote and will be used as-is, and will override any specified response() class.

I tried it and I give it a path for my sample.json file as below:

@ApiResponse(code = 200, message = "Success", response = WebServicesErrorResponse, reference = "http://localhost:9001/myinstanceofapplication/html/api-doc/hello.json")

and I also tried to give another path that is local path like below:

@ApiResponse(code = 200, message = "Success", response = WebservicesErrorResponse.class, reference = "C:/Desktop/hello.json")

but when swagger generate document for it then it gives following:

It is showing C:/Desktop/hello.json is not defined!

I have researched and tried lot many solutions but couldn't able to give proper reference to it. I found that this is an issue by https://github.com/swagger-api/swagger-ui/issues/1700 and https://github.com/swagger-api/swagger-js/issues/606.

So how can I use reference attribute of @ApiResponse to that swagger could show the sample XML/JSON swagger UI. My model class is below:

@XmlRootElement(name="response")
@XmlAccessorType(XmlAccessType.FIELD)
public class WebservicesErrorResponse
{
    @XmlElement
    private int code;

    @XmlElement
    private String message;

    public WebservicesErrorResponse(){ }


    public WebservicesErrorResponse(int code, String message)
    {
        this.code = code;
        this.message = message;
    }

    public int getCode()
    {
        return code;
    }
    public void setCode(int code)
    {
        this.code = code;
    }

    public String getMessage()
    {
        return message;
    }
    public void setMessage(String message)
    {
        this.message = message;
    }
} 

and I want to show following sample XML in the swagger UI:

<?xml version="1.0"?>
<response>
  <code>200</code>
  <message>success</message>
</response>

Answer 1

You need to annotate your model class (not the API resource/method!) with the @ApiModel and @ApiModelProperty annotations as described here.

For what you want to achieve, it would probably be enough to annotate your model members as follows:

@ApiModelProperty(example = "200")
@XmlElement
private int code;

@ApiModelProperty(example = "success")
@XmlElement
private String message;

If that doesn't work, try putting the annotation on the getters (I'm not really familiar with the XML side of this, have only done it for JSON).