ТипHint для коллекции в Enunciate

У меня есть некоторые службы REST (потребление и создание приложения /json ), и я использую @TypeHint для создания документации.

Теперь у меня есть что-то вроде этого:

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

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

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

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

но MyResponse является оболочкой над List<MyType>.

Мой build метод из MyResponse выглядит следующим образом:

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

Я хочу использовать непосредственно List<MyType> вместо MyResponse. Каков наилучший способ использования TypeHint в следующем коде?

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

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

Я думал о следующих вариантах:

  • @TypeHint(List.class)
  • @TypeHint(MyType.class)
  • @TypeHint(List<MyType>.class) → К сожалению, это не работает из-за стирания стилей Java.

Вопрос:

Существует ли допустимая альтернатива для номера 3?

Даже если тип List, число 1 не полезно, потому что мой собственный тип должен быть аннотирован с помощью @XmlRootElement и что List неизменен (это от JDK).

Существует обходной путь для числа 2, но он не совсем совершенен:

  • Используйте номер 2 (просто чтобы иметь доступный пример в сгенерированной документации HTML - описание элемента, содержащегося в этом списке)

  • Укажите, что это символ List в Javadoc (например: после слова @return) (его можно выделить жирным шрифтом, цветами, курсивом и т.д. с помощью HTML-тегов)

    Например:

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

Детали:

  • enunciate.version = 1.30.1
  • Java 7

Ответы

Ответ 1

Я выбрал использование класса MyType [] при использовании TypeHint вместо List.class. Таким образом, в документации будет указано "массив MyType", который для моего rest-api с json является истинным.

@TypeHint(value = MyType[].class)

Ответ 2

Как вы знаете, TypeHint используется, чтобы дать Enunciate подсказку о том, что возвращает метод ресурса JAX-RS или в качестве входного параметра.

В вашем случае описывается тип возврата.

Я предполагаю, что классReturnedByMyBuildersBuildMethod является подклассом абстрактного класса javax.ws.rs.core.Response. Для кода, как вы показали, вам нужно использовать класс, возвращаемый методом сборки MyBuilder - @TypeHint(ClassReturnedByMyBuildersBuildMethod.class).

Параметры 2 @TypeHint (MyType.class) не имеет смысла. Это не тип возврата и входной параметр.

Обновление 1: с обходным путем это может иметь смысл:)

Если вы добавите входной параметр в метод getIt - что-то вроде public Response getIt(List<MyType> myList){..., вы будете использовать параметр 1 (@TypeHint(List.class)), потому что, как вы знаете, org.codehaus.enunciate.jaxrs.TypeHint Объявление элемента типа аннотации имеет тип возврата Класс (Class<?> value();), и вы не можете использовать параметризованный тип beacuse для стирания родовых типов (в этом случае параметризованный тип имеет один и тот же класс во время выполнения - List).

Но изменение входного параметра на getIt(List<MyType> myList) , вероятно, не является жизнеспособным, потому что список должен быть получен из URI (с javax.ws.rs @QueryParam или @Context UriInfo). Этот вопрос описывает лучшие практики при использовании списка параметров в качестве входных данных, если это может вас беспокоить.

Обновление 2: Вариант 1 становится менее жизнеспособным из-за вашего ограничения XmlRootElement.

Обновление 3: я не вижу действительной альтернативы для варианта 3, используя аннотацию TypeHint как таковой.

Вам понадобится использовать обходной вариант 2.