Swagger generated REST API docs showing query para

问题:

I am generating swagger docs for my REST API. The generated docs show the params are required. How to make them not-required in swagger ? In actual REST invocations they are not-required (as expected); so problem is just in documentation.

import javax.ws.rs.*;

@GET
@Produces(MediaType.APPLICATION_JSON)
public Response getBaz(
        @DefaultValue("false") @QueryParam("foo") final boolean myFoo,
        @DefaultValue("") @QueryParam("bar") final String myBar
) { ... }

The generated swagger.json has

... "parameters":[{   ... snip "myBar":"bar","required":true}

回答1:

The @ApiParam annotation will do the trick. From the Swagger documentation:

The @ApiParam is used solely with the JAX-RS parameter annotations (@PathParam, @QueryParam, @HeaderParam, @FormParam and in JAX-RS 2, @BeanParam). While swagger-core scans these annotations by default, the @ApiParam can be used to add more details on the parameters or change the values as they are read from the code. [...]

According to the javadoc, you can use required to specify if the parameter is required or not. To use it, do as following:

@GET
@Produces(MediaType.APPLICATION_JSON)
public Response method(@ApiParam(value = "foo", required = false) @QueryParam("foo") boolean foo,
                       @ApiParam(value = "bar", required = false) @QueryParam("bar") String bar) { 
    ...
}

Check the javadoc for more details.