Collectives™ on Stack Overflow

Find centralized, trusted content and collaborate around the technologies you use most.

Teams

Q&A for work

Connect and share knowledge within a single location that is structured and easy to search.

I would like to add an example with Swagger in my method, I have tried a few things, but they didn't work.

I have my Interface, where I define the method:

@Api(value = "test API")
@RequestMapping("/api/v1/product")
public interface TestController {
    @ApiOperation(
            value = "Service that return a Product",
            notes = "This service returns a Product by the ID",
            nickname = "getProductById",
            response = ProductResponse.class)
    @ApiResponses(value = {
            @ApiResponse(code = 200, message = "The request has succeeded.", response = ProductResponse.class),
            @ApiResponse(code = 500, message = "Internal server error.", response = ProductResponse.class) })
    @GetMapping(
            value = "/productById",
            produces = { "application/json" }
    ResponseEntity<ProductResponse> getProductById(@RequestParam(value = "productId", required = true) String productId);
The ProductResponse class is the following:
@Getter
@Setter
@AllArgsConstructor
public class ProductResponse {
    private Product product;
    private CustomException customException;
The Product class is the following:
@Getter
@Setter
@AllArgsConstructor
public class Product {
    @JsonProperty("id")
    private String id;
    @JsonProperty("productName")
    private String productName;
    @JsonProperty("productDescription")
    private String productDescription;
    @JsonProperty("unitPrice")
    private Double unitPrice;
And the CustomException class is the following:
@Getter
public class CustomException {
    private final String message;
    private final String errorCode;
    private final String errorType;
    private final Exception exceptionDetail;
    public CustomException(String message, String errorCode, String errorType, Exception exceptionDetail) {
        this.message = message;
        this.errorCode = errorCode;
        this.errorType = errorType;
        this.exceptionDetail = exceptionDetail;
When the response is 200, the response is like:
  "product": {
    "id": "12345",
    "productName": "Product name",
    "productDescription": "This is a description",
    "unitPrice": 3.25
  "customException": null
But when the response is 500, the response is like:
  "product": "null,",
  "customException": {
    "message": "/ by zero",
    "errorCode": "500",
    "errorType": "Internal server error",
    "exceptionDetail": null,
    "cause": null,
    "stackTrace": [
        "classLoaderName": "app",
        "moduleName": null,
        "moduleVersion": null,
        "methodName": "getProductById",
        "fileName": "TestControllerImpl.java",
        "lineNumber": 33,
        "className": "com.myproject.testmicroservice.controller.impl.TestControllerImpl",
        "nativeMethod": false
How can I add a custom example in the @ApiResponse annotation?
You are probably missing the @Operation annotation, where inside you put the @ApiResponse.
Example:
  import io.swagger.v3.oas.annotations.responses.ApiResponse;
  import io.swagger.v3.oas.annotations.Operation;
  @Operation(responses = {
      @ApiResponse(responseCode = "200", content = @Content(examples = {
          @ExampleObject(name = "getUserAttribute",
                         summary = "Retrieves a User's attributes.",
                         description = "Retrieves a User's attributes.",
                         value = "[{\"value\": [\"area1\", \"area2\", \"area3\"], \"key\":\"GENERAL_AREAS\"}, {\"value\":\"933933933\", \"key\":\"FONyE\"}]")
      }, mediaType = MediaType.APPLICATION_JSON_VALUE))})
  public ResponseEntity<List<UserPreferenceDto>> getUserPreferenceByCode(
      @Pattern(regexp = "\\w+") @PathVariable String userCode, @Parameter(hidden = true) Pageable pageable) {
Good evening hope you are doing well. In the case you are describing, I would do something like this
@ApiResponses(value = { 
  @ApiResponse(responseCode = "200", description = "Found the book", 
    content = { @Content(mediaType = "application/json", 
      schema = @Schema(implementation = Book.class)) }),
  @ApiResponse(responseCode = "400", description = "Invalid id supplied", 
    content = @Content),
the approach described is explained here. I think that paragraph 9. Generate Documentation Using @Operation and @ApiResponses is of particular interest in your case. I hope this helps, Have a good night
You can try something like this. In your controller you already have @ApiResponses annotation. What you need to do is add @ApiModel to your Product class and then add
@ApiModelProperty(notes = "Your comments", required = true, example = "example value")
to members of your Product class i.e. ProductResponse and CustomException. One thing that you will need to verify is whether @ApiModelProperty can be set on custom objects like ProductResponse and CustomException. If not you will need to set @ApiModelProperty 1 level deep.
As shown in article, the examples are auto populated from model property to response.
PS: As of now, I do not have setup of a swagger project so can only help you theoretically.
may be this late answer but incase any one need it, you can add the requestBody description along with content type within @Operation
@io.swagger.v3.oas.annotations.Operation(summary = "", description = "",
        requestBody = @io.swagger.v3.oas.annotations.parameters.RequestBody(content = @Content(mediaType = MediaType.APPLICATION_JSON_VALUE)))
        
Thanks for contributing an answer to Stack Overflow!
Please be sure to answer the question. Provide details and share your research!
But avoid …
Asking for help, clarification, or responding to other answers.
Making statements based on opinion; back them up with references or personal experience.
To learn more, see our tips on writing great answers.