Swagger generated REST API docs showing query params as required (but I want not-required)

Question

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}

cassiomolin · Accepted Answer · 2015-12-09 13:28:48Z

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.

Thank you. Indeed that looks like it SHOULD do exactly as I want, but in my test just now, it made no difference i.e. I still see "required":true in the generated swagger.json !
@k1eran What version are you using? The current stable version is 1.5.4. An issue with @ApiParam was reported in old versions.
It turns out that my project is using its own custom maven-plugin to generate the swagger.json files (somewhat similar to github.com/swagger-api/swagger-codegen/blob/master/modules/… ) which unfortunately ignores the swagger-specific annotation @ApiParam and uses a different approach to detect that "required":true is needed. (I'm still not sure why my project has this approach; however as your advice is the correct solution for the "standard" swagger setup... thank you & I am accepting your answer.

Collectives™ on Stack Overflow

Swagger generated REST API docs showing query params as required (but I want not-required)

1 Answer 1

3 Comments

Linked

Hot Network Questions

Collectives™ on Stack Overflow

1 Answer 1

3 Comments

Linked

Related