使用 swagger 的注释在 Swagger UI 中显示 XML/JSON 示例值

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 = "") - 指定对响应类型的引用。指定的引用可以是本地的或远程的，将按原样使用，并将覆盖任何指定的 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 的引用属性到那个招摇可以显示示例 XML/JSON 招摇 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 注释将您的模型类（而不是API 资源/方法！）注释为described here。

对于您想要实现的目标，如下注释您的模型成员可能就足够了：

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

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

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