<p style="text-align: center;" ><img style="" src="https://oss-emcsprod-public.modb.pro/wechatSpider/modb__754cd91a-6187-11ec-9759-fa163eb4f6be.png"></p><p><br></p><p>本节会继续结合一个用户登录接口给大家介绍 Swagger 中的另一个注解 - ApiImplicitParam注解及所提供的常用属性。</p><p>ApiImplicitParam 注解经常来配合其他注解一同使用，并不会经常单独拿来使用，所以，对于 ApiImplicitParam 注解，我们只需要了解它的作用和注意事项即可，不必重点掌握。</p><p>重点讲解的属性：name 、value 、defaultValue 、 required ；<br>概要讲解的属性：paramType 、 dataType 。</p><p>希望大家在学习本节过程中能够分清主次，有的放矢。</p><p><br></p><p>ApiImplicitParam 注解是作用在<strong>接口方法上</strong>的注解，用来对该接口中的参数进行简短的描述，常常和 ApiParam 注解一起搭配使用。</p><p>ApiImplicitParam 注解提供了丰富的属性，来允许我们自定义接口方法中参数的描述信息，包括接口中参数是否必传、参数类型等。</p><p>下面我们来看一下 ApiImplicitParam 注解中都包括哪些主要属性。</p><p><br></p><div><thead><tr><th>属性名称</th><th>属性类型</th><th>默认值</th><th>作用</th></tr></thead><tbody><tr><td>name()</td><td>String</td><td>空</td><td>接口中参数名称</td></tr><tr><td>value()</td><td>String</td><td>空</td><td>接口中参数说明</td></tr><tr><td>defaultValue()</td><td>String</td><td>空</td><td>定义接口中参数的默认值</td></tr><tr><td>required()</td><td>boolean</td><td>false</td><td>定义接口中参数是否必传</td></tr><tr><td>paramType()</td><td>String</td><td>空</td><td>定义接口中参数使用位置</td></tr><tr><td>dataType()</td><td>boolean</td><td>空</td><td>定义接口中参数类型</td></tr></tbody></div><p><br></p><p><br></p><p><strong>定义：</strong></p><p>该属性就是描述接口中参数的名称。</p><p><strong>使用方法：</strong></p><p>在 ApiImplicitParam 注解中声明 name 

的值即可。例如，对于用户接口，该接口中存在一个用户对象参数 user ，我们只需要将 name 的值写为 ‘user’ 就好了，即表明该接口中有一个名称为 user 的参数（现在你不需要理解业务代码代表什么意思，重点看接口类上使用的注解及属性即可，下同）。

讯享网

代码解释：

第1行，我们在用户登录接口方法的上方，定义了 ApiImplicitParam 注解的 name 属性的值，来描述该方法中参数的名称。

显示结果：

讯享网

可以看到，在使用红色框框起来的地方就是我们使用 name 属性描述的参数名称了。

Tips ：

1. 在实际开发工作中，name 属性的值通常被描述为接口方法中参数的名称，一般情况不用单独来描述。
2. name 属性的使用不是必须的，即每个接口方法中不一定要使用 name 属性，name 属性的适用范围应该根据接口业务要求来定。

定义：

value() 属性就是对接口方法中的参数，进行简单必要的描述，即来描述接口方法中的参数是用来干什么的。

defaultValue() 属性就是定义接口方法中参数的默认值。

使用方法：

对于 value() 属性，在 ApiImplicitParam 注解中声明 value 的值即可，如果没有描述则默认值为空。例如，就用户登录接口而言，其中的 user 参数是用来接收用户的登录数据的，所以我们可以这样写，value = ‘user对象，用来接收用户的登录数据’ 如下代码段所示。

代码解释：

第1行，我们在用户登录接口方法的上方，定义了 ApiImplicitParam 注解的 value 属性的值来对该方法中的参数进行解释说明。

显示结果：

我们可以看到在红色框框起来的地方就是我们对接口方法中参数的解释说明。

对于 defaultValue() 属性，该属性值的定义需要根据接口中参数的类型而定，比如该用户登录接口中的参数类型是一个 user 对象，所以我们在描述的时候应该把 defaultValue() 属性的值使用 json 来填充。

defaultValue() 属性的演示我们会在后续章节-注解组合实战中给大家统一演示，希望大家关注。

Tips ： 在实际项目开发工作中，value 属性一般是每个接口方法都需要使用，而 value 属性值的定义则是需要做到简单扼要，切合实际，不能随意描述，需要根据具体业务场景来描述。

定义：

该属性就是对接口方法中参数传递的必要性进行约束，就是该接口方法中的参数是不是一定要传递。

使用方法：

在 ApiImplicitParam 注解中声明 required 的值即可，如果没有描述则默认值为 false 。例如，如果我想规定用户登录接口方法中的 user 参数是必须传递的，那么我可以这样写：required = true ,如下代码段所示。

讯享网

代码解释：

第1行，我们在用户登录接口方法的上方定义了 ApiImplicitParam 注解的 required 属性的值来要求该参数必须传递。

显示结果：

在我用红框圈起来的地方，我们可以看到在 user 的右上角有红色的 required 标识，这就是我们使用 required 规定参数必传的效果了。

Tips ：

1. required() 属性需要和 name() 属性一起来使用才能起到约束参数是否必传的目的，如果我们不使用 name() 属性，则 Swagger 就不会知道哪个参数需要 required 属性来描述。
2. required() 属性的定义请根据业务文档要求来描述，不要随意描述。

以上是对 ApiImpliciParam 注解中，经常使用的四个属性进行的详细介绍，name 、value 、defaultValue 、 required 这四个属性在使用 ApiImpliciParam 注解时经常使用，希望各位可以正确理解各属性所表达的含义，这是用好 ApiImpliciParam 注解的关键。

在详细讲解完 ApiImpliciParam 重要属性之后，下面我将针对在 ApiImpliciParam 注解中，使用频率不是很高，但是有时也会用到的一些属性做概要性讲解，这些属性分别是：paramType 、 dataType 。

定义：

paramType() 属性就是用来描述接口中的参数应该用在哪个地方，常用的位置有：header、query 、path 。

dataType() 属性就是用来描述接口中参数的类型。

使用方法：

如果我们需要描述接口方法参数的使用位置，那么我们可以直接在 ApiImplicitParam 注解中声明 paramType 的值即可。

dataType() 属性的默认值为 String 字符串类型，如果我们部队参数进行描述，则 Swagger 默认会使用该类型，如果需要明确定义接口中参数的类型，那就在 ApiImplicitParam 注解中声明 dataType 的值即可。

上述两种情况如下代码段所示：

代码解释：

第1行，我们在用户登录接口方法的上方定义了 ApiImplicitParam 注解的 paramType 属性和 dataType 属性来对接口方法中参数的使用位置和类型进行了描述。

由于篇幅限制，该部分注解的演示请参考注解组合实战章节。

Tips ： 在实际工作中，paramType 一般不常用，而 dataType 往往每个接口方法都需要使用。

以上则是 ApiImpliciParam 注解中的辅助使用属性的概要介绍，对于剩下的其他属性，在实际项目开发中几乎很少使用，在这里就不再介绍了，如果大家感兴趣，可以去 Swagger 的官网查询相关资料来了解。

本小节对 Swagger 中的 ApiImpliciParam 注解及其该注解的做了详细的讲解，针对 ApiImpliciParam 注解中经常在实际项目开发中使用的属性采用图文并茂的方式进行了重点介绍和应用剖析，对于一些在实际项目开发中使用基本很少的注解做了概要讲解。

在学习 @ApiImpliciParam 注解及其属性时，各位同学应该对比 @ApiParam 注解及其属性之间的使用差异，通过差异比较总结出适合自己的使用规律和使用方法才是最重要的。

本节会结合一个用户操作相关的实体类，来给大家介绍 Swagger 中的两个关联注解 - ApiModel 注解和 ApiModelProperty 注解及所提供的常用属性，使用率较低或基本不适用的注解属性就不再介绍了。

ApiModel 注解和 ApiModelProperty 注解，在实际项目中的使用频率较前面所介绍的注解而言相对较低，我们只需要了解它的作用和注意事项即可，不必重点掌握。

重点讲解的属性：

• ApiModel 注解的 value 、 description 属性；
• ApiModelProperty 注解的 value 、required 、hidden 、 allowEmptyValue 属性。

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

ApiModelProperty 注解是作用在接口相关实体类的参数上的注解，用来对具体的接口相关实体类中的参数添加额外的描述信息，常常和 @ApiModel 注解关联使用，有时也会单独拿出来用。

ApiModel 和 ApiModelProperty 两个注解的作用域不同，但是都提供了丰富的属性来允许我们对接口相关实体类和其中的参数添加额外的描述信息。

下面我们来看一下 ApiModel 和 ApiModelProperty 两个注解中都包括哪些主要属性。

ApiModel 注解

ApiModelProperty 注解

value() 属性

定义：

该属性就是对所需要特别说明的接口相关实体类进行描述。

使用方法：

讯享网

代码解释：

第1行，我们在用户实体类的上方定义了 ApiModel 注解的 value 属性的值，来对用户实体添加特定的描述信息。

显示结果：

可以看到，在之前显示 User 的位置，显示了我们使用 ApiModel 注解的 value 属性所描述的信息了。

Tips ： 在实际开发工作中，value 属性一般很少使用，只用默认的类型即可，如果有特别不直观的类名，则会考虑使用该注解的 value 属性。

description() 属性

定义：

description 属性就是对所需要特别说明的接口相关实体类进行较长的描述。

使用方法：

代码解释：

第1行，我们在用户实体类的上方定义了 ApiModel 注解的 description 属性的值来对用户实体添加额外的描述信息。

显示结果：

可以看到，在用红框圈起来的地方就是我们使用 description 属性来描述的信息了，值得注意的是，这里的显示样式是 Swagger 默认的，一般不需要修改。

Tips ：

1. 在实际开发工作中，description 属性一般会配合 value 属性进行使用，很少会出现只是用 value 属性而不使用 description 属性的情况。
2. description 属性使用频率同 value 属性。

value() 属性

定义：

该属性就是对实体类中的参数进行一个描述，即该属性用来对实体类中的字段做一个补充说明，来说明该字段代表什么意思。

使用方法：

讯享网

代码解释：

第1行，我们在 id 字段的上方定义了 ApiModelProperty 注解的 value 属性的值来对 id 字段补充说明。

显示结果：

可以看到，在用红框圈起来的地方就是我们使用 value 属性来描述的信息了。

Tips ： 在实际开发工作中，value 属性相对而言还是很常用的，value 属性的定义应该言简意赅，描述的时候不能太啰嗦。

required()、hidden() 属性

定义：

required 属性就是用来描述实体中的参数字段是否必传。

hidden 属性就是用来描述实体中参数字段是否显示在 Swagger 界面中。

使用方法：

代码解释：

第1行，我们在 id 字段的上方定义了 ApiModelProperty 注解的 required 属性的值为 true ，代表该字段必传。

第3行，我们在 phone 字段的上方定义了 ApiModelProperty 注解的 hidden 属性为 true ， 代表该字段不在 Swagger  界面上显示。

显示结果：

可以看到，id 字段的后面有一个红色的星号，这表明该字段必传，这就是 required 属性所起的作用。

在整个实体字段中并不能看到 phone 字段，这就是我们使用 hidden 属性所起的作用，我们可以对比上述 value 属性的结果图来看。

Tips ：

1. 在实际开发工作中，hidden 属性不能滥用，如果哪些字段需要隐藏，请向项目经理提出申请。
2. required 属性相对而言还是经常使用的，required 属性的定义应当根据具体的业务需求，不要随意定义，这会引起不必要的麻烦。

allowEmptyValue() 属性

定义：

allowEmptyValue 属性是用来描述实体参数的值是否可以为空。

使用方法：

在 ApiModelProperty 注解中直接声明 allowEmptyValue 属性的值即可，如果我们不声明该属性，则默认为 false，即字段参数的值不可以为空。

讯享网

代码解释：

第1行，我们在 phone 字段的上方定义了 ApiModelProperty 注解的 allowEmptyValue 属性的值为 true ，代表该字段的值可以为空，在参数传递时可以不填充值。

显示结果：

可以看到，在序号为 1 的标签红框中的 id 字段上，我们并没有定义 allowEmptyValue 属性，所以他默认将该属性描述为了 false ， 即 id 参数的值在传递时不可以为空，必须为其填写数据。

在序号为 2 标签红框中的 phone 字段上，我们定义了 allowEmptyValue 属性的值为 true ，即 phone 参数的值在传递时可以为空，这就是 allowEmptyValue 属性所起的作用。

Tips ： 在实际开发工作中，allowEmptyValue 属性经常和 required 属性一起搭配使用，但是同样不能滥用，如果哪些字段的值需要在传递时为空，请向项目经理提出申请。

本小节对 Swagger 中的 ApiModel 和 ApiModelProperty 注解及其该注解做了详细讲解，针对两个注解中，经常在实际项目开发中使用的属性，采用图文并茂的方式，进行了重点介绍和应用剖析，由于不同注解的很多属性用法相同，这里就不再赘述了。

在学习 ApiModel 和 ApiModelProperty 注解及其常用属性时，各位同学应该在清楚，什么是实体类的基础上进行学习，因为这两个注解都是针对实体类而言的，其他地方无法使用。

本节会继续结合用户登录接口方法来为大家介绍 Swagger 中的两个关联注解 - ApiResponse 和 ApiResponses 注解及所提供的常用属性，使用率较低或基本不适用的注解属性就不再介绍了。

ApiResponse 和 ApiResponses 注解在实际项目中的使用频率较前面所介绍的注解而言相对较低，我们只需要掌握他们最的基本用法和常用属性即可。

重点讲解的属性：

• ApiResponse 注解的 code 、message 、responseHeaders 属性；
• ApiResponses 注解的 value  属性。

ApiResponse 注解是作用在接口方法上的注解，用来对该接口方法的一个或多个返回值进行描述，一般不会单独使用，常常和 @ApiResponses 注解配合使用。

ApiResponses 注解也是作用在接口方法上的注解，作用和 @ApiResponse 注解相同，只是在当有多个 @ApiResponse 注解同时存在时才会使用该注解。

ApiResponse 和 ApiResponses 注解是一组关系紧密的注解，主要使用的属性都在 @ApiResponse 注解中。

下面我们来看一下 ApiResponse 和 ApiResponses 两个注解中都包括哪些常用属性。

ApiResponse 注解

ApiResponses 注解

code () 和 message () 属性

定义：

code 属性就是描述接口返回的响应数据的状态码。

message 属性就是对接口返回的响应数据的状态码进行描述。

使用方法：

在 ApiResponse 注解中直接声明 code 属性和 message 属性的值即可，例如，对于用户登录接口，我想添加一个值为 666 的状态码，其描述为 success ，代表当接口返回的状态码为 666 时表示请求是成功（success）的。

鉴于上述业务场景，我们可以这样写：code = 666, message = “success”(现在你不需要理解业务代码代表什么意思，重点看实体类上使用的注解及属性即可，下同 。

代码解释：

第 1 行，我们在用户登录接口方法的上方定义了 ApiResponse 注解的 code 属性的值为 666，message 属性的值为 success 来对用户登录接口添加特定的返回信息。

显示结果：

可以看到，在用红框框起来的地方就是我们使用 code 属性和 message 属性所展示的效果了。

Tips ：

1. 一般而言，在实际项目开发中，http 协议自带的返回状态码已经够用了，不需要开发者再特殊指定，如果业务要求必须遵照一定的规则，那就只能额外规定了。

responseHeaders () 属性

定义：

该属性就是对接口的返回头做一个描述，即犹如请求接口时所规定的请求头为 ‘application/json’ 类型那样。

使用方法：

在 ApiResponse 注解中，直接声明 responseHeaders 属性的值即可，例如，我想把用户登录接口的返回头类型定义为‘multipart/file’ (这样定义显然是不合理的，这里只做演示) ，则可以这样写：description = “用户实体中包含用户相关的所有业务字段，如有需要请另行添加” 。

讯享网

代码解释：

第 1 行，我们在用户实体类的上方定义了 responseHeaders 属性的值来对用户登录接口的返回头类型添加额外的描述信息。由于篇幅原因这里就不给大家截图了。

Tips ：

1. responseHeaders 属性值的定义应该按照 http 协议规定好的类别进行描述，如果我们所描述的不是 http 协议所规定的类型，那么在 Swagger 界面上是不会显示出来的，这点需要注意。
2. responseHeaders 属性虽然是 ApiResponse 注解中的，但是使用该属性需要以数组的形式使用，即如上述代码示例，因为该注解源码中就是这样定义的。

value () 属性

定义：

ApiResponses 注解的 value 属性就是对接口的返回状态码及其返回状态码描述进行多条描述，来说明该接口的返回格式有多条额外的描述。

使用方法：

ApiResponses 注解规定其 value 属性的类型为 ApiResponse 数组类型，这就说明 value 属性只能使用 @ApiResponse 注解的形式进行描述，同时允许描述多条。

例如，在用户登录接口中，我想对该接口的返回格式添加两条额外描述信息，使用方法如下所示。

代码解释：

1-3 行，我们在用户登录接口方法的上方定义了 ApiResponses 注解的 value 属性来对该接口的返回格式添加两条额外描述信息。

显示结果：

可以看到，600 和 666 及其 error 和 success 就是我们使用 value 属性来对该接口的返回格式添加的额外描述信息了。

Tips ：

1. 在实际开发工作中，value 属性经常被用来描述一个接口方法的多条返回格式，其内容应该根据业务文档所规定的要求进行描述。
2. value 属性内容的填充形式就如上述代码所示，其中 value 这个单词可以不显式的写出来，Swagger 会默认隐藏。
3. ApiResponses 注解不能单独使用，因为他只有一个类型为 ApiResponse 数组形式的 value 属性，即要使用 ApiResponses 注解就必须要填充 value 属性。

本小节对 Swagger 中的 ApiResponse 和 ApiResponses 注解，及其该注解中的常用属性，做了详细介绍，针对两个注解中，经常在实际项目开发中使用的属性，采用图文并茂的方式进行了重点介绍和应用剖析。

Tips : 值得注意的是 @ApiResponse 注解一般不可以单独拿来使用，需要搭配 @ApiResponses 注解一起来使用，这样才能在 Swagger-ui 界面看到使用效果。

在学习 ApiResponse 和 ApiResponses 注解及其常用属性时，各位同学应该在清楚常见的 http 状态码及其描述都有哪些以及什么是接口的请求头、响应头的基础上进行学习，因为这两个注解都是针对接口的返回数据及其格式而言的，其他地方无法使用。