Swagger / springfox 自动生成响应示例

Posted 2023-02-26

【中文标题】Swagger / springfox 自动生成响应示例

【英文标题】：Swagger / springfox generating response example automatically

【发布时间】：2019-05-06 03:31:24

【问题描述】：

目前使用 springfox 2.9.2 来 Swagger 记录一个在 Spring 中创建的 API。 我想在文档中添加示例响应，如下图所示；

我的理解是我可以做类似的事情：

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

在这种情况下，我将此代码 sn-p 放在 GET 方法的上方。 不幸的是，上面的 2 个示例总是显示：标识符预期错误

但我也看到我也可以这样做：

@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=  )

我的问题是：

如何向我的 Swagger 文档添加示例 JSON 响应？

最好将 Swagger/Springfox 指向我的模型/bean 并让它自动生成示例响应，并随着 bean/模型的每次更新自动更新。这是上面第二个代码sn-p应该做的吗？

【问题讨论】：

实际上，swagger 文档是通过localhost:<yourport>/v2/api-docs 访问的。你在上面厌倦的一切都应该反映在那里。请检查并确认。

感谢@Code_Is_Law 的评论，在我的情况下，当我添加上面的sn-ps 时代码甚至没有编译。你有一个可以编译的样本吗？另外，您的意思是 /v2/api-docs 将显示与我在 /swagger-ui.html 中看到的不同的 JSON 吗？再次感谢

@Tlink，你能解决这个问题吗？我也在使用@ApiResponses(value = ...)，而IntelliJ 表示我的值中每个@ApiResponse 的末尾都有一个identifier expected 错误。错误显示在每个的右括号中。

您使用的是 Java 还是其他 JVM 语言？这是我关于错误的问题。然而，我仍然收到一个空的 JSON 响应示例。

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

【参考方案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;