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做过). (编辑:李大同) 【声明】本站内容均来自网络,其相关言论仅代表作者个人观点,不代表本站立场。若无意侵犯到您的权利,请及时与联系站长删除相关内容! |