TypeHint für Sammlung in Enunciate

Question

Ich habe einige REST-Dienste (konsumieren und Erstellen von Anwendung/JSON) und ich @TypeHint verwenden, um Dokumentation zu generieren.

Jetzt habe ich so etwas wie dieses:

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

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

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

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

aber MyResponse ist ein Wrapper über List<MyType>.

Meine build Methode von MyResponse sieht wie folgt aus:

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

ich direkt List<MyType> statt MyResponse verwenden möchten. Welches ist der beste Weg, TypeHint im folgenden Code zu verwenden?

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

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

ich zu den folgenden Optionen dachte:

1. @TypeHint(List.class)
2. @TypeHint(MyType.class)
3. @TypeHint(List<MyType>.class) -> leider ist dies nicht wegen der Löschung Java-Typ arbeiten.

Frage:

Gibt es eine gültige Alternative für Nummer 3?

---

Auch wenn der Typ ist eine List, Anzahl nicht sinnvoll ist, weil meine eigene Art mit @XmlRootElement kommentiert werden muss und dass List ist unveränderlich (es von JDK ist).

Es gibt ein Abhilfe für Nummer , aber es ist nicht ganz perfekt:

• Nrn. 2 (nur in der generierten HTML-Dokumentation ein verfügbares Beispiel zu haben - eine Beschreibung für ein Element, das ist in dieser Liste enthalten ist)

• angeben, dass es sich um ein List in Javadoc (ZB ist: nach dem @return Wort) (betont werden kann fett, Farben, kursiv, etc. über HTML-Tags)

  Z. B .:

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

Details:

• enunciate.version = 1,30.1
• Java 7

Answer 1

Wie Sie wissen TypeHint verwendet wird enunciate einen Hinweis darüber, was eine JAX-RS Ressource Methode gibt oder akzeptiert als Eingangsparameter zu geben. In Ihrem Fall wird der Rückgabetyp beschrieben.

Ich nehme an, dass die ClassReturnedByMyBuildersBuildMethod eine Unterklasse der abstrakten Klasse javax.ws.rs.core.Response ist. Für den Code, wie Sie es gezeigt haben, was Sie verwenden müssen, ist die Klasse, die von MyBuilders Build-Methode zurückgegeben wird - @TypeHint(ClassReturnedByMyBuildersBuildMethod.class).

Optionen 2 @TypeHint (MyType.class) macht keinen Sinn. Es ist weder ein Rückgabetyp noch ein Eingabeparameter.

Update 1: mit Ihrem Problem zu umgehen es einen Sinn :)

Wenn Sie einen Eingabeparameter der Methode getIT hinzufügen machen kann - so etwas wie public Response getIt(List<MyType> myList){... Sie Option 1 (@TypeHint(List.class)) verwenden würde, weil, wie Sie das wissen org.codehaus.enunciate.jaxrs.TypeHint Annotationstyp Element-Deklaration hat einen Klasse Rückgabetyp (Class<?> value();) und Sie können nicht eine parametrisierte Typ beacuse die Löschung von generischen Typen (die paramterized Typ der gleiche Klasse zur Laufzeit in dieser Fall - Liste).

Aber die Änderung der Eingangsparameter getIt(List<MyType> myList)ist wahrscheinlich nicht rentabel, weil die Liste würde von der URI erhalten werden müssen (mit javax.ws.rs der @QueryParam oder @Context UriInfo). This question behandelt Best Practices bei der Verwendung der Liste von Parametern als Eingabe, wenn Sie davon betroffen sein könnten.

Update 2: Option 1 wird aufgrund Ihrer XmlRootElement-Einschränkung weniger praktikabel.

Update 3: Ich sehe keine gültige Alternative für Option 3 mit der TypeHint Annotation, wie es ist.

Sie müssen mit Ihrer benutzerdefinierten Option 2 Problemumgehung gehen.

Answer 2

Ich habe mich für die Verwendung von MyType []. Class entschieden, wenn TypeHint anstelle von List.class verwendet wird. Auf diese Weise wird in der Dokumentation "array of MyType" angegeben, was für meine Rest-API mit json gilt.

@TypeHint(value = MyType[].class)