TypeHint for collection in Enunciate

Question

I have some REST services (consuming and producing application/json) and I use @TypeHint to generate documentation.

Now I have something like this:

import javax.ws.rs.core.Response;
...

@Path("/path")
public class MyClass {

    @GET
    @TypeHint(MyResponse.class)
    public Response getIt() {

        MyResponse resp = ... ;
        return MyBuilder.build(resp);
    }
}

but MyResponse is a wrapper over List<MyType>.

My build method from MyResponse looks like this:

public static Response build(Serializable payload) {
    return Response.ok(msr).header(...).build();
}

I want to use directly List<MyType> instead of MyResponse. Which is the best way to use TypeHint in the following code?

    @GET
    @TypeHint(/* TODO */)
    public Response getIt() {

        List<MyType> myList = ... ;
        return MyBuilder.build(myList);
    }

I was thinking to the following options:

1. @TypeHint(List.class)
2. @TypeHint(MyType.class)
3. @TypeHint(List<MyType>.class) -> unfortunately this doesn't work because of Java type erasure.

Question:

Is there a valid alternative for number 3?

---

Even if the type is a List, number 1 is not useful because my own type has to be annotated with @XmlRootElement and that List is unchangeable (it is from JDK).

There is a workaround for number 2, but it's not quite perfect:

• Use number 2 (just to have an available example in the generated HTML documentation - a description for an element that is contained in that list)

• Specify that it is a List in Javadoc (E.g.: after the @return word) (it can be emphasized using bold, colors, italics, etc. via HTML tags)

  E.g.:

  /**
   * ...
   * @return <strong><font color="blue">List&lt;MyType&gt;</font></strong>
   */
  

Details:

• enunciate.version = 1.30.1
• Java 7

Answer 1

I have opted for using MyType[].class when using TypeHint instead of List.class. This way the documentation will state "array of MyType" which for my rest-api with json is true.

@TypeHint(value = MyType[].class)