自动生成响应示例的Swagger / Springfox

Question

目前使用Springfox 2.9.2来swagger文档化创建的API。我想在文档中添加示例响应，就像这张图片中一样;

我理解的是可以做类似于这样的事情:

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

在这种情况下，我将此代码片段放在GET方法上面。不幸的是，上述两个示例始终显示：标识符预期错误。

但我也发现我可以这样做：

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

我还发现我可以在@ApiOperation级别上添加示例：

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

我的问题是：

1. 我如何将一个示例 JSON 响应添加到我的 Swagger 文档中？

2. 最理想的情况是只需将 Swagger/Springfox 指向我的模型/bean，并自动生成示例响应，并在每次 bean/model 更新时自动更新。这是上面第二个代码片段的预期作用吗？

- Tlink

---

实际上，Swagger文档可以通过http://localhost:<yourport>/v2/api-docs访问。您在上面尝试的所有操作都应该反映在那里。请确认并检查。 - Code_Is_Law

感谢 @Code_Is_Law 的评论，在我的情况下，当我添加了上述代码片段时，代码甚至无法编译。您是否有一个可以编译的示例？另外，您的意思是 /v2/api-docs 将显示与我在 /swagger-ui.html 中看到的不同的 JSON 吗？再次感谢。 - Tlink

@Tlink，你解决了这个问题吗？我也在使用 @ApiResponses(value = ...)，但是 IntelliJ 在每个 @ApiResponse 的末尾显示出现了“预期标识符”错误。该错误在每个值的结束括号处显示。 - Rob

你是用Java还是其他JVM语言？这是我遇到的问题。但是我仍然收到一个空的示例JSON响应。 - Tlink

在ExampleProperty中指定mediaType解决了我的问题。 - Rishabh Bhatnagar

Answer 1

为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

---

如何自定义日期类型？示例字段无用。 - BlackC