Query parameter annotation generated as body param in Swagger?

Question

I have a Restlet API application using the Restlet Swagger extenstion to generate the Swagger json via Swagger2SpecificationRestlet .

// route to generated swagger json
swagger2SpecificationRestlet.attach(router, "/docs");  

My routes are defined like this:

router.attach("/path/{pathParam}", MyResource.class);

I have implemented swagger-ui locally and set the initializer url to read the swagger json from /docs . The UI works as expected for all of the routes including the required path parameter inputs however the annotations for the query params are rendering as post body(?) without any of the other defined fields. param inputs:

"parameters": [
    {
        "name": "pathParam",
        "in": "path",
        "required": true,
        "type": "string"
    },
    {
        "in": "body",
        "name": "body",
        "required": false,
        "schema": {
        "type": "string"
    }
],

My resource method with annotations:

    @ApiOperation(
        value="test desc",
        httpMethod = "GET", 
        produces = "application/json", 
        notes="testing notes"
    )
    @Get("txt")
    public String represent(
        @ApiParam(name="queryParam", value = "testing desc") 
        @QueryParam("queryParam") String queryParam
        ) throws SQLException { ... }

How can I annotate query params so that swagger generates the correct json configuration?

Answer 1

After looking further into the documentation I came across this:

https://docs.swagger.io/swagger-core/apidocs/com/wordnik/swagger/annotations/ApiImplicitParam.html#paramType()

which states:

public @interface ApiImplicitParam Represents a single parameter in an API Operation. While ApiParam is bound to a JAX-RS parameter, method or field, this allows you to manually define a parameter in a fine-tuned manner. This is the only way to define parameters when using Servlets or other non-JAX-RS environments.

I replaced ApiParam with ApiImplicitParam which has a field to declare param type and moved the annotation above the method:

    @ApiOperation(
        value="get stuff",
        httpMethod = "GET", 
        produces = "application/json", 
        notes="test notes"
    )
    @Get("txt")
    @ApiImplicitParam(
        name="queryParam", 
        dataType = "String", 
        paramType = "query", 
        value = "testing query param desc", 
        defaultValue = "default val")
    public String represent() throws SQLException {
        return getMethod();
    }

Which results in the correctly generated json:

"parameters": [
    {
        "name": "pathParam",
        "in": "path",
        "required": true,
        "type": "string"
    },
    {
        "name": "queryParam",
        "in": "query",
        "description": "testing query param desc",
        "required": false,
        "type": "string",
        "default": "default val"
    }
]