Question

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

我们的服务界面包含一个用于列出的自定义@QueryParam注释方法实现支持的所有查询参数。我不想解释现在为什么我们决定拥有一个自定义@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文档时？

Answer 1

您可以尝试使用@ResourceMethodSignature注释明确告诉Enunciate该方法尝试执行的操作。 More info here.

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

如果这些都不起作用，我唯一能想到的就是创建一个自定义的Enunciate模块来设置自定义@QueryParams注释试图声明的模型。 More (but not much) info here.

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

枚举自定义@QueryParam注释

2 个答案: