java - Swagger 使用@ApiParam或@ApiModelProperty？

以下两个注释均适用于向swagger-ui文档添加元数据。应该选择哪一个，为什么？

public class MyReq {

    @ApiModelProperty(required = true, value = "the persons name")
    @ApiParam(required = true, value = "the persons name")
    private String name;
}

@RestController
public class MyServlet {
   @RequestMapping("/")
   public void test(MyReq req) {

   }
}

最佳答案

两者之间存在巨大差异。它们都用于添加元数据，但是它们添加了不同的元数据。
@ApiParam 用于参数。通常在API资源请求类中定义。

@ApiParam的示例:

/users?age=50

它可用于定义参数年龄和以下字段:

paramType:查询

名称:年龄

描述:

用户的年龄

为必填项:true

@ApiModelProperty 用于添加模型的属性。
您将在模型属性的模型类中使用它。

例:

模型用户将名称和年龄作为属性:名称和年龄，然后可以为每个属性定义以下内容:

对于年龄:

类型:整数，

格式”:int64，

说明:用户年龄

checkout 每个在swagger对象中表示的字段:

@ ApiModelProperty- https://github.com/OAI/OpenAPI-Specification/blob/master/versions/1.2.md#529-property-object

@ApiParam-https://github.com/OAI/OpenAPI-Specification/blob/master/versions/1.2.md#524-parameter-object