enunciate docs issue with Iterable and generics

Question

I’m trying to use enunciate to regenerate documentation for my Jersey-based REST API. Hitting a few stumbling blocks:

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

Enunciate doesn’t seem to be able to interpolate the Iterable. In my docs I just get “element: (custom)”. Note that the Project type is annotated with @XmlRootElement and @JsonRootType.

Similarly, for this code:

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

I get “element: (custom)” for both the method parameter (note: T has an extends restriction) as well as the return type (where Response is: javax.ws.rs.core.Response). Moreover, enunciate can’t seem to figure out the Media Type of the return: it lists XML, JSON, and * (come to think of it, I’m not sure exactly what I would want there, but I know it’s not that.)

Any ideas?

Answer 1

Enunciate uses the JAX-RS spec to generate its documentation. Unfortunately, the Iterable interface isn't a formally-supported JAX-RS object type, so somehow you're using a custom message body writer to serialize out Iterable to JSON (Jackson, I presume?).

So if you want to be for formal about your return type, you can create a wrapper bean that Enunciate can recognize and return that instead of Iterable, e.g.:

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