Enunciate custom @QueryParam annotation

Question

I am using Enunciate to generate documentation for my Resteasy services. I am able to generate the documentation needed, but I have an issue regarding some custom parameters.

Our service interface consist of a custom @QueryParam annotation which is used to list all query parameters the method implementation support. I don't want to explain now why we decided to have a custom @QueryParam, it was just an architectural decision.

Despite all now Enunciate doesn't recognize the custom @QueryParam so all my Resteasy methods are without @QueryParam parameters (only @PathParam).

Sample service interface:

@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;

Implementation of @QueryParam class:

@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 {};
}

Implementation of @QueryParams class:

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

Is there a way to tell Enunciate to take in consideration also my custom @QueryParam while generating HTML documentation?

Answer 1

You might be able to try using the @ResourceMethodSignature annotation to explicitly tell Enunciate what the method is trying to do. More info here.

You might be able to try applying both the @QueryParams annotation and the @QueryParam annotation.

If neither of those work, the only thing I can think of would be to create a custom Enunciate module that sets up the model that the custom @QueryParams annotation is trying to declare. More (but not much) info here.

Answer 2

OK, with @ResourceMethodSignature I am able to get all parameters (query and path) in the documentation. The only disadvantage is that I need to list the parameters once again inside @ResourceMethodSignature. If you forget to update also the @ResourceMethodSignature when adding new parameters (or deleted) the documentation will be out-of-sync.

Example:

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

When you "read" all @javax.ws.rs.QueryParam do you think you could consider also other annotations?