How to add "Example Value" to a parameter in Swagger

Question

I'm creating a new Rest API with Spring Boot using Swagger to document it and I can't change the Example Value showed on the web. I'm able to change it in the model, but not in the POST parameter.

These are my dependencies:

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.1.4.RELEASE</version>
        <relativePath/>
        <!-- lookup parent from repository -->
    </parent>
...
        <swagger.version>2.9.2</swagger.version>
...
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>${swagger.version}</version>
        </dependency>
        <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>${swagger.version}</version>
        </dependency>
...

The code that I have is:

    @PostMapping("events")
    @ApiOperation(value = "Get events")
    public ResponseEntity<List<Event>> events(
            @ApiParam(value = "Event type", required = true, example = "sent") final @RequestBody String type) {
        return new ResponseEntity<List<Event>>(getEvents.get(type), HttpStatus.OK);
    }

Instead of seeing under example value 'sent', y see 'string'.

This annotation works fine for the Event model, but not here.

What I'm I missing?

Other issue with your code is that POST method should be used for creating new record. To get list of records you should be using GET method (and @GetMapping annotation). — user12690733, Jan 10 '20 at 16:38

score 5 · Accepted Answer · answered May 02 '19 at 10:42

According to the documentation of @ApiParam - example attribute is

a single example for non-body type parameters

However you used @RequestBody annotation for your string parameter. In your case: change the @RequestBody annotation to @RequestParam and you should be able to see the provided example in the Swagger UI:

@PostMapping("events")
@ApiOperation(value = "Get events")
public ResponseEntity<List<Event>> events(
    @ApiParam(value = "Event type", required = true, example = "sent") final @RequestParam String type) {
        return new ResponseEntity<List<Event>>(getEvents.get(type), HttpStatus.OK);
    }

For body parameters there is examples attribute. Check the Springfox Reference Documentation how to use it.

...
examples = @io.swagger.annotations.Example(
        value = {
            @ExampleProperty(value = "{'property': 'test'}", mediaType = "application/json")
        })) 
}
...

How to add "Example Value" to a parameter in Swagger

1 Answers1