想要在Swagger中记录可选的JSON参数-Java 学习之路

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

举一个具体的例子，假设我有一个看起来像这样的POJO：

public class pojo {
    private String val1;
    private String val2;
    private String val3;
    //getters, setters, constructors, etc.
}

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

作为一个相关问题，我如何为响应机构做类似的事情？就像使用上面的POJO一样，我怎么能说“在响应时，你应该期望val1为空，val2可能有一个值或者可能为null，而val3应该有一个值，假设服务成功”？

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会考虑这些注释，它应该反映在文档中：

Swagger UI

在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

回复于 2024-04-20T22:24:21+08:00