大摇大摆地使用@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 Resource 请求类中。

@ApiParam 的例子：

/users?age=50

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

• 参数类型：查询
• 姓名年龄
• 描述：用户年龄
• 要求：真实

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

例子：

model User 具有 name 和 age 作为属性：name 和 age 然后对于每个属性，您可以定义以下内容：

对于年龄：

• 类型：整数，
• 格式”：int64，
• 描述：用户的年龄，

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

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

   }
}