generics - 用 Iterable 和泛型阐述文档问题

Question

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

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

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

同样，对于此代码：

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

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

有任何想法吗？

Answer 1

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

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

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