Swagger ui - Query param

Question

I am using Swagger ui and Swagger core (1.3) for a jersey application. I have certain query parameters which I must send with every request like post, get, delete...

How can I default this ?

Could you choose a correct response ? – Nelson G. Feb 13 '17 at 07:33 — Nelson G., Feb 13 '17 at 07:33

score 15 · Answer 1 · answered Jul 02 '15 at 03:05

15

You can use the annotation @ApiParam from the Swagger annotations in order to configure the Query param to be used from the Swagger-UI.

For example

@Path("/{username}")
@ApiOperation(value = "Updated user")
public Response updateUser(
  @ApiParam(value = "description for query-parameter") @QueryParam("username") String username
) {
...
}

Please, read more about this annotation in the following official documentation: https://github.com/swagger-api/swagger-core/wiki/Annotations#apiparam

answered Jul 02 '15 at 03:05

ipeluffo

535
3
6

ApiParam for queryparam can be used only if the operation has such parameter in its definition. But, here I want to send a Query parameter with the url that will be accessed when a post or get or delete operation is tried out. Hope you understand what I am looking for – Jacaro Jul 02 '15 at 16:44
In the scope of the function, check if the variable's value is `null`. If it is, that means the query parameter was not specified in the HTTP request. That is, you can do `if (username == null) { username = "myDefaultValue"; }`. – Jivan Pal Jan 18 '22 at 11:26

score 1 · Answer 2 · answered Jul 01 '15 at 21:05

You can't, but since swagger 2.0 (I don't know if this is supported by swagger-code/swagger-ui), you can defines parameters to be reuse across operations.

For example :

{
  "parameters": {
    "pageParam": {
      "name": "page",
      "in": "query",
      "description": "page number to get",
      "required": false,
      "type": "integer",
      "format": "int32"
    }
  },
  "paths": {
    "/customers": {
      "get":  {
        "description": "Retrive list of customers",
        "parameters": {
          "$ref": "#/parameters/pageParam"
        },
        ...
      }
    }
  },
  ...
}

score 1 · Answer 3 · answered Sep 14 '22 at 20:44

1

For swagger version 3, you can use the annotation @Parameter

import io.swagger.v3.oas.annotations.Parameter

https://docs.swagger.io/swagger-core/v2.0.0-RC3/apidocs/io/swagger/v3/oas/annotations/Parameter.html

answered Sep 14 '22 at 20:44

Ilya Y

744
6
24

score 0 · Answer 4 · answered Aug 08 '23 at 11:12

Building on @Ilya Y's answer here's a snippet from a controller I had using io.swagger.v3.oas.annotations.Parameter;

@PostMapping("/report")
public FileItem generateReport(
        @RequestParam String projectId,
        @RequestParam @DateTimeFormat(iso = ISO.DATE) @Parameter(schema = @Schema(type = "string", description = "Date in ISO format (yyyy-MM-dd)")) LocalDate date,
        @RequestParam(defaultValue = "UTC") String zoneId //
) {
...
}

Swagger ui - Query param

4 Answers4