声明自定义@QueryParam注释

Question

我正在使用公文为我的餐厅服务生成文档。我能够生成所需的文档，但是对于一些自定义参数，我有一个问题。

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

尽管现在所有的声明都不承认自定义的@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();
}

在生成@QueryParam文档时，是否也要考虑到我的自定义的HTML呢？

Answer 1

您可以尝试使用@ResourceMethodSignature注释显式地告诉所述方法要做什么。这里有更多信息。

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

如果这两种方法都不起作用，我唯一能想到的就是创建一个自定义声明模块，该模块将建立自定义@QueryParams注释试图声明的模型。这里有更多(但不多)的信息。

Answer 2

好的，通过@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时，您认为还可以考虑其他注释吗？