我有一些REST服务(使用和生成application / 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的包装。
我来自MyResponse的build方法看起来像这样:
public static Response build(Serializable payload) {
return Response.ok(msr).header(...).build();
}
我想直接使用List而不是MyResponse。在以下代码中使用TypeHint的最佳方法是哪种?
@GET
@TypeHint(/* TODO */)
public Response getIt() {
List myList = ... ;
return MyBuilder.build(myList);
}
我在考虑以下选项:
@TypeHint(List.class)
@TypeHint(MyType.class)
@TypeHint(List.class)->不幸的是,由于Java类型擦除,此方法不起作用。
题:
3号有有效的替代方法吗?
即使类型是List,数字1也没有用,因为我自己的类型必须用@XmlRootElement注释,并且List是不可更改的(来自JDK)。
对于数字2,有一种解决方法,但这不是很完美:
使用数字2(只是为了在生成的HTML文档中提供可用示例-该列表中包含的元素的描述)
在Javadoc中指定它为List(例如:在@return单词之后)(可以通过HTML标记使用粗体,颜色,斜体等进行强调)
例如。:
/**
* ...
* @return List
*/
细节:
enunciate.version = 1.30.1
Java 7
我选择使用TypeHint而不是List.class时使用MyType []。class。这样,文档将声明" MyType数组",对于我的带有json的rest-api,它为true。
@TypeHint(value = MyType[].class)
这可能是一个更好的答案,但是不幸的是,现在我无法对其进行测试以确认您是否正确。
如您所知,TypeHint用于向Enunciate提供有关JAX-RS资源方法返回或接受为输入参数的内容的提示。
在您的情况下,将描述返回类型。
我假设ClassReturnedByMyBuildersBuildMethod是javax.ws.rs.core.Response抽象类的子类。
对于显示的代码,您需要使用MyBuilder的生成方法-@TypeHint(ClassReturnedByMyBuildersBuildMethod.class)返回的类。
选项2 @TypeHint(MyType.class)没有任何意义。它既不是返回类型也不是输入参数。
更新1:通过您的解决方法,这可能会有些道理:)
如果将输入参数添加到getIt方法-类似于public Response getIt(ListmyList){...,则将使用选项1(@TypeHint(List.class)),因为众所周知,org.codehaus.enunciate.jaxrs.TypeHint注释类型元素声明具有Class返回类型( Class< ? > value();),并且由于删除通用类型而不能使用参数化类型(在这种情况下,参数化类型在运行时共享相同的类-List)。
但是将输入参数更改为getIt(ListmyList)可能不可行,因为必须从URI(使用javax.ws.rs的@QueryParam或@Context UriInfo)获取列表。此问题解决了在您可能将参数列表用作输入时的最佳做法。
更新2:由于XmlRootElement约束,选项1变得不太可行。
更新3:我看不到使用TypeHint注释的选项3的有效替代方案。
您将必须使用自定义选项2解决方法。
1)我同意你的第一句话。 2)是的,我的构建器返回了Response 3)我从未尝试将Response类型用于TypeHint,因为当我使用"包装"的类型时,它可以完美地工作(根据我想要实现的目的) 回应。 4)我不使用List作为函数的参数。 它包装在返回的结果中。 根据您的建议,我需要尝试一下,然后才能说出您的答案是否有用。
它没有工作。 element的值被视为(custom),而不是指向JSON示例的超链接。 因此,这并不比问题中所述的解决方法更好。
我更新了您所做修改的答案。