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

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?
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 }

score 6 · Accepted Answer · answered Jul 31 '17 at 22:18

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.

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

Thanks Sergii - Allowable values only seem to be values that are allowable but not where I can specify default values for the response type under Example Value? The ApiModelProperty helped out a lot. — PacificNW_Lover, Aug 01 '17 at 07:53
@PacificNW_Lover y, you can't specify default values for model with `ApiModelProperty`. May be later they provide this ability, will see. — Sergii, Aug 01 '17 at 08:26
I use`@ControllerAdvice` to provide correct response builder with clean code. Each exception contains information about validated fields or unsupported operations. Some times I have not enough data to provide into my customRuntimeExceptions. In this case I use general exception information to provide default data for `CustomResponse`. I hope it helps. — Sergii, Aug 01 '17 at 08:57
can you provide an example of your ControllerAdvice? "... you have overridden code - default message mapping." Where did I do this? — PacificNW_Lover, Aug 02 '17 at 17:50
I think controller advice should be different question. I can't add here `ControllerAdvice` example in comments because of restricted space. I can't add example into different answer or in same because of general question was about different part. Ask one more question, put link in comments, I'll add answer and example. Is it ok for you? — Sergii, Aug 02 '17 at 21:00

Swagger Annotations for Customizing Responses?

1 Answers1