jax-rs – 使用swagger的注释在Swagger UI中显示XML / JSON样本值

我正在实现基于Jersey的REST API并使用swagger生成基于 HTML的文档.我正在使用swagger的注释来读取和扫描资源以生成文档.我已使用@ApiResponse注释为每个资源指定了响应,如下所示：

@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();
    }
}

它工作正常,它生成基于HTML的文档,如下所示：

因为它显示响应代码为404时响应的完整结构(模型和示例值).在示例值中,它不显示值,仅显示模型的每个参数的类型.

我想展示响应的示例示例模式,以便客户端可以理解每个响应的确切响应.我研究了它,我发现有一个属性：

@ApiResponse(reference =“”) – 指定对响应类型的引用.指定的引用可以是本地引用,也可以是远程引用,将按原样使用,并将覆盖任何指定的response()类.

我尝试了它,并为我的sample.json文件提供了如下路径：

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

我还试图给出另一条路径,就像下面的本地路径一样：

@ApiResponse(code = 200,reference = "C:/Desktop/hello.json")

但是当swagger为它生成文档时,它会给出以下结果：

它显示C：/Desktop/hello.json未定义！

我已经研究并尝试了很多解决方案,但无法正确引用它.我发现这是https://github.com/swagger-api/swagger-ui/issues/1700和https://github.com/swagger-api/swagger-js/issues/606的问题.

那么我如何使用@ApiResponse的引用属性来表示该样式的XML / JSON swagger UI.我的模型类如下：

@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;
    }
}

我想在swagger UI中显示以下示例XML：

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

您需要使用@ApiModel和@ApiModelProperty注释注释您的模型类(而不是API资源/方法！)作为 described here.

对于您想要实现的目标,可能足以注释您的模型成员,如下所示：

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

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

如果这不起作用,请尝试将注释放在getter上(我不太熟悉这方面的XML方面,只为JSON做过).