1

我正在使用 Enunciate 为我的 Resteasy 服务生成文档。我能够生成所需的文档，但我对一些自定义参数有疑问。

我们的服务接口包含一个自定义@QueryParam注释，用于列出方法实现支持的所有查询参数。我现在不想解释为什么我们决定有一个 custom @QueryParam，这只是一个架构决定。

尽管现在 Enunciate 无法识别自定义@QueryParam，所以我所有的 Resteasy 方法都没有@QueryParam参数（仅@PathParam）。

示例服务接口：

@GET
@Path("{regionId}/{userId}/validate-access")
@Produces({ MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML })
@QueryParams(uniqueName = "validatePin", params = {
        @QueryParam(param = Param.PIN, isRequired = true),
        @QueryParam(param = Param.PIN_TYPE, isRequired = false, valueSet = { "valueA", "valueB" }, defaultValue = "valueA") })
StatusResponseResult validatePin(@Context HttpServletRequest hsr, @PathParam("regionId") int regionId,
        @PathParam("userId") int userId, @Context UriInfo info) throws RestApiException;

@QueryParam 类的实现：

@Retention(RetentionPolicy.RUNTIME) 
public @interface QueryParam {
    public Param param();
    public boolean isRequired() default false;
    public boolean canBeEmpty() default true;
    public String defaultValue() default "";
    public String minValue() default "";
    public String maxValue() default "";
    public String format() default "";
    public String[] valueSet() default {};
}

@QueryParams 类的实现：

@Retention(RetentionPolicy.RUNTIME)
public @interface QueryParams {
    String uniqueName();
    QueryParam[] params();
}

有没有办法告诉 Enunciate@QueryParam 在生成 HTML 文档时也考虑我的自定义？

4

2 回答 2

0

好的，使用 @ResourceMethodSignature 我可以获取文档中的所有参数（查询和路径）。唯一的缺点是我需要在@ResourceMethodSignature 中再次列出参数。如果您在添加新参数（或删除）时忘记更新 @ResourceMethodSignature，则文档将不同步。

例子：

@ResourceMethodSignature(
      pathParams = { @PathParam("regionId"),@PathParam("userId") },
      queryParams = { @javax.ws.rs.QueryParam("pin"), 
                      @javax.ws.rs.QueryParam("pin_type") }
)

当您“阅读”所有 @javax.ws.rs.QueryParam 时，您认为您还可以考虑其他注释吗？

于 2013-08-07T21:16:43.107 回答
0

您也许可以尝试使用@ResourceMethodSignature注释来明确地告诉 Enunciate 该方法试图做什么。更多信息在这里。

您也许可以尝试同时应用注释@QueryParams和注释@QueryParam。

如果这些都不起作用，我唯一能想到的就是创建一个自定义 Enunciate 模块，该模块设置自定义@QueryParams注释试图声明的模型。更多（但不多）信息在这里。

于 2013-08-07T15:27:09.250 回答