Swagger Annotations for Customizing Responses?

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 }

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).