java - 在 Swagger 中使用@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

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

• 参数类型:查询
• 姓名:年龄
• 描述:用户年龄
• 必填:true

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

示例:

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

年龄:

• 类型:整数，
• 格式”: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