Swagger Annotations for Customizing Responses?

Question

Have a custom response setup like this:

public class CustomResponse {
    private int id;
    private String productName;
    private int quantity;
    private double price;

    // Constructor & along with Getters & Setters

}

My Swagger inside my ProductController:

@RestController
@RequestMapping("/api/v1")
public class ProductController {

    @ApiOperation(httpMethod = "GET", 
                  value = "Retrieves reesults based on specific values set in the request parameters.", 
                  notes = "Sends back query results in JSON format after being processed.", 
                  produces = "application/json")
    @ApiResponses(value = { 
                        @ApiResponse(code = 200, message = "Successful GET command", response = CustomResponse.class),
                        @ApiResponse(code = 400, message = "Bad Request"),
                        @ApiResponse(code = 404, message = "Entity Not Found"), 
                        @ApiResponse(code = 500, message = "Internal Server Error") 
                        })
    @RequestMapping(value = "/products", method = RequestMethod.GET, produces="application/json" )
    public ResponseEntity<Object> getQueryResults(@ApiParam(value = "productName", required = true) @RequestParam(value = "productName") String productName) throws IOException {
        // Implementation details
    }
}

My pom.xml:

    <!-- Swagger -->
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>2.6.1</version>
        <scope>compile</scope>
    </dependency>

    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>2.6.1</version>
        <scope>compile</scope>
    </dependency>

When I launch my webservice and open up Swagger's UI, I see a Model and Example Value for the CustomResponse...

Question(s):

1. How can I describe / document the individual attributes of the CustomRepsonse inside the Swagger? Meaning, is there a Swagger annotation to describe each field of the CustomResponse?

2. In the Example Value, is there a way I can also document the attributes with actual hardcoded data?

Right now, its showing up like this in Example Value:

{ "id" : 0, "productName" : "string","quantity" : 0, "price" : 0.00 }

Answer 1

How can I describe / document the individual attributes of the CustomRepsonse inside the Swagger? Meaning, is there a Swagger annotation to describe each field of the CustomResponse?

Please pay your attention on annotation @io.swagger.annotations.ApiModelProperty - it should help you to add doc for customResponse

public class CustomResponse {
    private int id;
    @io.swagger.annotations.ApiModelProperty(value = "my super product name")
    private String productName;
    @io.swagger.annotations.ApiModelProperty(allowableValues = "1,5,10,25,50")
    private int quantity;
    private double price;

    // Constructor & along with Getters & Setters

}

In the Example Value, is there a way I can also document the attributes with actual hardcoded data?

Definitely you can specify default values for ApiParam . I do not think there is a way to specify default data via swagger annotation for CustomResponse fields. Partly you can cover your needs using annotation @io.swagger.annotations.ApiModelProperty .

• overriding-property-datatypes
• allowableValues
• other properties of the ApiModelProperty - java doc

---

Using swagger you can define web doc for CustomResponse but default values will be specified by default in the class level (constructor or field declaration). To make it more flexible I prefer use @ControllerAdvice where I configure exception handlers and here I have chance map code on correspond exception and specify values for my custom responses (default values too).

---

As I can see in your swagger doc you have overridden code - default message mapping. To make it working it would be useful to change some configuration (pay your attention on .useDefaultResponseMessages(false) and followed rows responsible for this).