招摇使用@ApiParam或@ApiModelProperty？

Question

以下注释都适用于向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) {

   }
}

Answer 1

两者之间存在巨大差异。它们都用于向swagger添加元数据，但它们添加了不同的元数据。

@ApiParam 用于参数。它通常在API资源请求类中定义。

@ApiParam示例：

/users?age=50

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

• paramType：query
• 姓名：年龄
• description：用户年龄
• required：true

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

示例：

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

适合年龄：

• 类型：整数，
• 格式＆＃34;：int64，
• description：用户年龄

查看每个在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

Answer 2

主要区别

简单地说，@ApiParam 和 @ApiModelProperty 注释为 Swagger 添加了不同的元数据。

@ApiParam 注释用于 API 资源请求的参数，而 @ApiModelProperty 用于属性 模型（大多数情况下为 DTO）。

---

@ApiParam 示例

我们将有一个 API 来创建用户，方法是通过查询参数发送 firstName 和 lastName 并获得 UserDTO 响应。 >

在代码中：

我们使用 @ApiParam 作为 firstName 和 lastName。

在 Swagger 中：

---

@ApiModelProperty 示例

我们有一个 UserDTO 模型，其中包含 id、firstName、lastName 作为属性。所有这些属性都将使用 @ApiModelProperty 进行注释。

在代码中：

在 Swagger 中：

---

如果您不注释来自请求方法的参数或来自模型的属性，它们在 Swagger 中将不可见。