Question

我正在实现基于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 =＆＃34;＆＃34;） - 指定对响应类型的引用。指定的引用可以是本地引用，也可以是远程引用，将按原样使用，并覆盖任何指定的response（）类。

我试过了，我为它的sample.json文件提供了一个路径，如下所示：

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

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

@ApiResponse(code = 200, message = "Success", response = WebservicesErrorResponse.class, 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的引用属性来表示swagger可以显示示例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>

Answer 1

您需要使用@ApiModel和@ApiModelProperty注释described here注释您的模型类（而不是API资源/方法！）。

对于您想要实现的目标，可能足以按如下方式注释您的模型成员：

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

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

如果这不起作用，请尝试将注释放在getter上（我并不熟悉这方面的XML方面，只为JSON做过）。

使用swagger的注释

1 个答案: