想要在Swagger中记录可选的JSON参数

Question

我有一个我正在尝试使用Swagger记录的API。我的API将POJO作为通过RequestBody中的JSON的输入，并同样将POJO作为JSON返回为ResponseBody。我的JSON对象中的某些字段可为空，而其他字段则为必填字段。我希望我的Swagger文档反映哪些字段可以为空，哪些字段是必需的。有没有一种方法可以简单地做到这一点，而无需创建Swagger配置文件，该文件可能比在文本编辑器中手动记录API的时间长？

作为一个具体示例，假设我有一个看起来像这样的POJO：

<form method='post'>
<input required  type = 'text' name = 'txt_name' value='$username' />
<input required  type = 'text' name = 'txtemail' value='$email' /><br>
<input required  type = 'text' name = 'txt_total' value='$total'/>
<input type='submit' name='btn_save' value='Proceed'/>
<input onclick='window.history.back()' type='button' value='Back' />
</form>

假设我希望我的Swagger文档告诉读者：“应要求，不要发送val1（例如，此API是数据库插入，而val1对应于应该自动生成的表的PK）， val2是可选的，而val3是必需的”。我该怎么做？

作为一个相关问题，我该如何对响应正文进行类似的处理？像使用上面的POJO一样，我怎么能说“在响应时，假设服务成功，您应该期望val1为空，val2可能有一个值或可能为null，而val3应该有一个值”？

Answer 1

为了记录POJO对象中的可选参数，可以使用@ApiModelProperty属性，例如：

public class pojo {
    @ApiModelProperty(value = "This parameter will be ignored", required = false)
    private String val1;
    @ApiModelProperty(value = "This parameter is optional", required = false)
    private String val2;
    @ApiModelProperty(required = true)
    private String val3;
    //getters, setters, constructors, etc.
}

Swagger将考虑这些注释，并且应将其反映在文档中：

在yaml API文档中：

pojo:
    type: object
    required:
      - val3
    properties:
      val1:
        type: string
        description: This parameter will be ignored
      val2:
        type: string
        description: This parameter is optional
      val3:
        type: string