18

Currently using springfox 2.9.2 to Swagger document an API created in Spring. I want to add example response in the documentation, like in this image;

enter image description here

my understanding is that I can do something similar to this:

@ApiResponses(value = {
    @ApiResponse(code = 200, message = "Success", 
            examples = @io.swagger.annotations.Example(
                value = {
                    @ExampleProperty(value = "{'snapshot'：{'type': 'AAA'}}", mediaType = "application/json") 
                }))

I'm placing this code snippet just above the GET method in this case. unfortunately the 2 examples above always shows : identifier expected error

But I also see that I can do this too:

@ApiResponses(value = {
    ApiResponse(code = 200, message = "Success", response = MyModel.class,
    )
})

Also I see that I can add an example with @ApiOperation level:

@ApiOperation(value = "Create a Account", nickname = "createAccount", notes = "Create a account", response = AccountResponse.class, tags={  })

My questions are:

  1. How can I add an example JSON response to my Swagger documentation?

  2. It would be ideal to just point Swagger/Springfox to my model/bean and have it generate the example response automatically, and automatically update with each update for the bean/model. Is this what the second code snippet above is supposed to do?

Tlink
  • 875
  • 2
  • 14
  • 30
  • Actually the swagger docs are accessed via http://localhost:/v2/api-docs. Everything you tired above should reflect there. Do check and confirm. – Code_Is_Law Dec 05 '18 at 10:40
  • Thanks @Code_Is_Law for the comment, in my case the code did not even compile when I've added the above snippets. Do you have a sample that would compile? Also, do you mean that /v2/api-docs will show a JSON that's different than what I see in /swagger-ui.html? thanks again – Tlink Dec 05 '18 at 17:05
  • @Tlink, were you able to resolve this issue? I am also using `@ApiResponses(value = ...)` and IntelliJ is indicating that there is an `identifier expected` error at the end of each `@ApiResponse` in my value. The error shows up at the closing parenthesis for each. – Rob Apr 28 '19 at 07:16
  • Are you using Java or another JVM language? this was my issue regarding the error. Yet I'm still getting an empty sample JSON response. – Tlink Apr 29 '19 at 16:11
  • specifying mediaType in ExampleProperty solved my issue. – Rishabh Bhatnagar Dec 24 '21 at 15:36

1 Answers1

3

Define example with annotation for dto:

@ApiModel("Crop")
public class CropDto {

    @ApiModelProperty(name = "Unique guid", position = 1, example = "7aaee0e2-6884-4fd7-ba63-21d76723dce2")
    public UUID id;
    @ApiModelProperty(name = "Unique code", position = 2, example = "squ")
    public String code;
    @ApiModelProperty(name = "Unique name", position = 3, example = "Squash")
    public String name;
    @ApiModelProperty(position = 4, example = "Cucurbita pepo L.")
    public String description;
}
Oleg Cherednik
  • 17,377
  • 4
  • 21
  • 35