Annotating @FormParam fields with Swagger-UI @ApiParam

Question

I have built a RestEasy API and linked it with Swagger UI . A task I have been asked to complete is to, find a way to reduce the query parameters in the method signature and handle them in some sort of "DTO".

My original implementation would be similar to:

  @GET
  @ApiOperation(value = "echo test value", notes = "echo test notes")
  @ApiResponse(code = HttpServletResponse.SC_OK, message = "Response.status.OK")
  public Response echoTest(
    @ApiParam("id") @QueryParameter("id") final int id,
    @ApiParam("fName") @QueryParameter("fName") final String fName,
    @ApiParam("sName") @QueryParameter("sName") final String sName) {

    // handle request

  }

I have extracted the query-parameter handling to a DTO, although now I am unsure how to handle the Swagger-UI side of things. I have tried to annotate the fields in the DTO athough as I guessed, this did not work. My current solution without correct swagger-ui interaction:

  @GET
  @ApiOperation(value = "echo test value", notes = "echo test notes")
  @ApiResponse(code = HttpServletResponse.SC_OK, message = "Response.status.OK")
  public Response echoTest(@ApiParam("form") @FormParam QueryDTO dto) {

    //Handle request

  }

QueryDTO.java:

public class QueryDTO {

  @ApiParam(name = "id", value = "user id") @QueryParam("id") private int id;
  @ApiParam(name = "fName", value = "user first name") @QueryParam("fName") private String fName;
  @ApiParam(name = "sName", value = "user surname") @QueryParam("sName) private String sName;

  // Getters,setters etc

}

Does SwaggerUI support this type of feature? Is there an alternative approach I could take which would suit my use case? Any suggestions or help is appreciated, thanks.

Answer 1

The issue here isn't Swagger-UI but rather Swagger-Core.

Swagger-Core doesn't support RESTEasy's @Form annotation and only supports standard JAX-RS annotations.

I was unfamiliar with that annotation until you mentioned it, but it looks like it acts the same way as @BeanParam which was introduced in JAX-RS 2.0. Support for it should be provided with RESTEasy 3.0 and above. Swagger-core is able to process @BeanParam's in order to produce proper documentation.

If you still want just support for @Form, you'd have to open an issue on Swagger-Core's repository.