swagger注解大全（swagger 实体类注解）

大家好，我是讯享网，很高兴认识大家。

持续创作，加速成长！这是我参与「掘金日新计划 · 6 月更文挑战」的第18天，点击查看活动详情

作者平台：

| CSDN：blog.csdn.net/_…

| 掘金：juejin.cn/user/…

| 知乎：www.zhihu.com/people/1024…

| GitHub：github.com/JiangXia-10…

| 微信公众号：1024笔记

本文一共2058字，预计阅读7分钟

最近新的项目使用到了Swagger进行接口测试，在实体类上使用到了两个注解，一个是ApiModel注解，还有一个是ApiModelProperty注解，今天就一起学习下这两个注解的用处、属性以及具体的使用。

首先来说说，ApiModel 注解和 ApiModelProperty 注解到底是干嘛用的。毕竟它们两个还是很像的。

讯享网

首先@ApiModel注解是用在接口相关的实体类上的注解，它主要是用来对使用该注解的接口相关的实体类添加额外的描述信息，并且常常和@ApiModelProperty注解配合使用。

而@ApiModelProperty注解则是作用在接口相关实体类的属性（字段）上的注解，用来对具体的接口相关实体类中的参数添加额外的描述信息，除了可以和 @ApiModel 注解关联使用，也会单独拿出来用。

所以可以理解为ApiModel和 ApiModelProperty两个注解的作用域不同，它们都是作用在接口相关的实体类上用来进行额外信息的描述，只是一个是作用在类上，一个作用在属性上。毕竟Property的中文意思就是属性。

使用它们需要导入swagger的依赖：

讯享网

首先看下它的具体使用和源码：

讯享网

源码如下：

所以可以发现其主要的属性有value属性和description属性。

value属性就是对所需要特别说明的接口相关实体类进行描述。具体使用就如上面的例子一样，如果不适用value时，默认值就是实体类的名称，所以除非有特殊说明或者实体类不清晰，否则直接使用默认值即可。

description属性就是对所需要特别说明的接口相关实体类进行较长的描述。比如上面的例子，如果想对用户实体添加必要的描述信息，可以如下所示：

讯享网

还是先看具体使用和源码：

源码：

讯享网

可以发现ApiModelProperty注解的属性较多，这里就不进行一一演示，其中使用较多的属性有：value、name、required 、hidden以及allowEmptyValue属性。

value属性就是对实体类中的字段进行描述和补充说明，解释该字段代表什么意思。比如，如果上述的实体类中的id字段信息，可以对其进行描述，比如：

所以可以理解为它就是一个注释的作用，方便清楚字段的含义。

name属性即重写该属性名字，比如上述例子，name可以这样使用：

讯享网

required属性就是用来描述实体中的参数字段是否必传,默认false，如果使用true，则该字段后面会有一个红色的星号，比如：

hidden属性就是用来描述实体中参数字段是否显示在Swagger界面中，默认也是false，true表示隐藏。比如：

讯享网

allowEmptyValue属性是用来描述实体参数的值是否可以为空值。在 ApiModelProperty 注解中直接声明 allowEmptyValue属性的值即可，如果不声明该属性，则默认为false，即字段参数的值不可以为空。

比如如果想使得master字段声明其值可以为空，即在参数传递时可以不填充值：

example属性表示对该字段进行举例，比如name字段，值可以是张三：

讯享网

dataType属性表示的是字段的类型，比如age字段是int类型：

本文主要介绍了Swagger中的常用到的ApiModel注解和ApiModelProperty注解，并对这两个注解的使用和常用的属性进行了解释和演示。可以理解为ApiModel和 ApiModelProperty两个注解的作用域不同，它们都是作用在接口相关的实体类上用来进行额外信息的描述，只是一个是作用在类上，一个作用在属性上。毕竟Property的中文意思就是属性。

Springboot处理请求参数的注解
Spring常用注解大全，值得你的收藏！！！
Spring注解(七)：使用@Value对Bean进行属性赋值
SpringBoot开发Restful风格的接口实现CRUD功能
SpringCloud系列：OpenFeign组件

swagger注解大全（swagger 实体类注解）

相关推荐