java - Enunciate 中收集的 TypeHint

Question

我有一些 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<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);
    }

我在考虑以下选项:

1. @TypeHint(List.class)
2. @TypeHint(MyType.class)
3. @TypeHint(List<MyType>.class) -> 不幸的是，由于 Java 类型删除，这不起作用。

问题:

是否有有效的替代数字 3？

---

即使类型是 List , number 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

Answer 1

在使用 TypeHint 而不是 List.class 时，我选择使用 MyType[].class。这样，文档将声明“MyType 数组”，这对于我的带有 json 的 rest-api 是正确的。

@TypeHint(value = MyType[].class)