用 Iterable 和泛型阐述文档问题答案

【问题标题】：enunciate docs issue with Iterable and generics用 Iterable 和泛型阐述文档问题
【发布时间】：2013-02-06 03:43:20
【问题描述】：

我正在尝试使用 enunciate 为我的基于 Jersey 的 REST API 重新生成文档。遇到一些绊脚石：

@GET
@Produces(MediaType.APPLICATION_JSON)
public Iterable<Project> listAll() {
    ...
}

Enunciate 似乎无法插入 Iterable。在我的文档中，我只得到“元素：（自定义）”。请注意，Project 类型使用@XmlRootElement 和@JsonRootType 进行注释。

同样，对于这段代码：

@POST
@Consumes(MediaType.APPLICATION_JSON)
public Response save(final T persistable) {
    ...
}

我为方法参数（注意：T 具有扩展限制）和返回类型（其中 Response 为：javax.ws.rs.core.Response）都获得了“元素：（自定义）”。此外，enunciate 似乎无法弄清楚返回的媒体类型：它列出了 XML、JSON 和 *（想想看，我不确定我到底想要什么，但我知道不是那样.)

有什么想法吗？

【问题讨论】：

标签： generics documentation iterable enunciate

【解决方案1】：

Enunciate 使用 JAX-RS 规范生成其文档。不幸的是，Iterable 接口不是正式支持的 JAX-RS 对象类型，因此不知何故，您正在使用自定义消息正文编写器将Iterable 序列化为 JSON（我猜是Jackson？）。

因此，如果您想要正式地说明您的返回类型，您可以创建一个 Enunciate 可以识别并返回它的 wrapper bean，而不是 Iterable，例如：

@XmlRootElement
public class Projects {
  public Collection<Project> projects;
}

【讨论】：