本节会继续结合一个用户登录接口给大家介绍 Swagger 中的另一个核心注解 - Api注解及所提供的常用属性。
Api 注解和 ApiOperation 注解一样，在 Swagger 中都扮演着非常重要的角色，Api 注解一般都会配合 ApiOperation 注解一起来使用。
重点讲解的属性：value 、tags 、description ;
概要讲解的属性：consumes、produces、protocols、hidden 。
希望大家在学习本节过程中能够分清主次，有的放矢。
Api 注解是作用在接口类上面的注解，其主要是用来给接口类定义相关说明。
Api 注解提供了丰富的属性，来允许我们自定义接口类的描述信息，包括对接口类的简单描述，接口类所属的分组等。
下面我们来看一下 Api 注解中都包括哪些主要属性。
| 属性名称 | 属性类型 | 默认值 | 作用 |
|---|---|---|---|
| value() | String | 空 | 接口类说明 |
| tags() | String[] | 空 | 定义接口类所属分组 |
| description() | String | 空 | 定义接口类的简单描述 |
| protocols() | String | 空 | 网络请求协议 |
| hidden() | boolean | false | 接口类隐藏 |
| produces() | String | 空 | 接口类请求头类型-输出 |
| consumes() | String | 空 | 接口类请求头类型-输入 |
定义：
该属性就是描述接口类的作用是什么，即同一类下的接口都是用来干什么的。
使用方法：
在 Api 注解中声明 value 的值即可。例如，对于用户接口类（UserController），我们只需要将 value 的值写为 'user-controller’就好了，这样我们就能很清楚的知道这个接口类下的所有接口都是用来处理和用户相关的请求的，如下代码段所示（现在你不需要理解业务代码代表什么意思，重点看接口类上使用的注解及属性即可，下同）。
@Api(value = "user-controller")public class UserController{// do something...}
代码解释：
第1行，我们在 UserController 用户接口类的上方使用了 @Api 注解的 value 属性来描述该接口类的作用。
显示结果：
可以看到，在 Created by Steafan 下放黑体加粗显示的 user-Controller 就是我们使用 value 属性描述的接口类信息了。
Tips ：
通过 value 属性来对接口类进行描述的这一行为在实际开发工作中并不常用，各位同学只需要知道有这么一个 value 属性就可以了。
在实际开发工作中， value 属性经常被 tags 属性所替代，这也是 Swagger 官方所设定的规则：当 Api 注解的 value 属性和 tags 属性同时存在时，tags 属性的值会替代 value 属性的值，这一点需要同学们注意。
定义：
该属性就是对实现相同业务功能的接口类做一个大型的分组，该分组中包括同业务功能下的所有的接口。
使用方法：
在 Api 注解中声明 tags 的值即可，如果没有描述则默认值为空。例如，就用户接口类而言，该接口类属于用户业务分组，所以我们将 tags 的值描述为'用户’或者'user’，这样我们就能很清楚的看到这个接口类是属于用户业务组的，如下代码段所示。
@Api(tags = {"user"})public class UserController{// do something...}
代码解释：
第1行，我们在 UserController 接口类的上方使用了 @Api 注解的 tags 属性来描述该接口类所属的业务分组。
显示结果：
我们可以看到在 value 属性的值的位置显示了 user ，也就是 tags 里写的 user 了。
上述是 tags 属性和 value 属性单独存在时候的效果，下面我们来看一下 tags 属性和 value 属性同时存在的效果，如下代码段所示：
@Api(value="user-controller", tags = {"user"})public class UserController{// do something...}
代码解释：
第1行，我们在 UserController 接口类的上方使用了 @Api 注解的 value 属性和 tags 属性同时来描述该接口类。
显示结果：
我们可以看到显示结果是和只使用 tags 属性来描述接口类时相同的结果，这也证明了 Swagger 官方的设定。
Tips ： 在实际项目开发工作中，往往一个业务可能包括多个接口类的实现，这种情况需要我们对接口类进行多个分组，而 tags 属性的类型是字符串类型的数组，可以描述一个或多个值，如存在多值时，应该使用这种方式来描述：@Api(tags = {“user”, “customer”})。
定义：
该属性就是对接口类进行简单概要的描述，通常是描述一些注意的地方，value 属性更多的则是描述接口类的用途，这一点同学们要分清。
使用方法：
在 Api 注解中声明 description 的值即可，如果没有描述则默认值为空。例如，如果我想添加对用户接口类的概要描述信息，那么我可以这样写 description = “所有用户业务接口必须使用post请求”，如下代码段所示。
@Api(description = {"所有用户业务接口必须使用post请求"})public class UserController{// do something...}
代码解释：
第1行，我们在 UserController 接口类的上方使用了 @Api 注解的 description 属性来描述用户接口类的一些注意的地方和约定。
显示结果：
在我用红框圈起来的地方我们可以看到使用 description 注解所描述的信息了。
Tips ：
description 属性一般用来对接口类进行一些注意事项和约定的描述，不要将其描述为接口类的用途。
description 属性在实际开发工作中还是很常用的，所以描述好 description 是体现一个程序员对业务内容是否充分理解的标志。
以上是对 Api 注解中经常使用的三个属性进行的详细介绍，value，tags，description 这三个属性不管是在项目开发中，还是在需求沟通中，使用的都很频繁，所以真正掌握这三个属性，是用好 Api 注解的重要前提。在学习这三个属性时，大家应该结合 ApiOperation 注解来对比并总结它们之间的差异，通过不断的使用来发现它们的使用规律，这一点很重要。
在详细讲解完 Api 重要属性之后，下面我将针对在 Api 注解中，使用频率不是很高，但是有时也会用到的一些属性做概要性讲解，这些属性分别是：consumes、produces、protocols、hidden。
定义：
protocols() 属性就是对接口类中，所有的接口所使用的网络协议进行一个约定，常用的网络协议有：http、https。
hidden() 属性就是控制接口类在 Swagger 界面中的显隐性。
使用方法：
protocols() 属性默认值为空，但是 Swagger 在处理时，会默认获取项目所采用的网络协议，我们可以不用专门设置，如果一定要设置该属性，则只允许设置http协议规定的属性，不能随意设置，http, https 这些都是被允许的。
hidden() 属性允许我们在 Swagger 生成的接口列表界面上，控制接口类是否需要显示，默认值为 false，即接口类显示，为true时则接口类不显示，如下代码段所示。
@Api(hidden = true)public class UserController{// do something...}
代码解释：
第1行，我们在 UserController 接口类的上方使用了 @Api 注解的 hidden 属性来隐藏我们的用户接口类。
Tips ：
接口类的显隐控制应该根据特定安全策略和特定客户需求来决定显隐，不能无故隐藏接口，更不能频繁的切换接口的显隐。
在实际工作中，如果需要隐藏接口类则需要和项目组报备情况，说明原因。
以上则是 Api 注解中的辅助使用属性的概要介绍，对于剩下的 produces、consumes 属性在实际项目开发中几乎很少使用，在这里就不再介绍了，如果大家感兴趣可以去 Swagger 的官网查询相关资料来了解。
本小节对 Swagger 中另一个最经常使用的 Api 注解及其该注解的各个属性做了详细的讲解，针对 Api 注解中经常在实际项目开发中使用的属性采用图文并茂的方式进行了重点介绍和应用剖析，对于一些在实际项目开发中使用基本很少的注解做了概要讲解。
在学习 @Api 注解及其属性时，各位同学应该对比 @ApiOperation 注解及其属性之间的使用差异，通过差异比较总结出适合自己的使用规律和使用方法才是最重要的。
本节会继续结合一个用户登录接口给大家介绍 Swagger 中的另一个核心注解 - ApiParam 注解及所提供的常用属性。
ApiParam 注解一般会结合 ApiOperation 注解以及 Api 注解一起来使用。
重点讲解的属性：name 、value 、defaultValue 、allowableValues 、required ；
概要讲解的属性：access、allowMultiple、example、hidden。
希望大家在学习本节过程中能够分清主次，有的放矢。
ApiParam 注解，是可以作用在接口方法上面，以及接口方法中的参数位置的注解，其主要是用来给接口中的参数定义相关参数说明，主要是为了，帮助相关人员理解接口中每个参数的含义。
ApiParam 注解同样也提供了丰富的属性，来允许我们对接口中的参数添加描述信息，包括该参数的具体含义、参数是否必须传递等。
下面我们来看一下 ApiParam 注解中都包括哪些主要属性。
| 属性名称 | 属性类型 | 默认值 | 作用 |
|---|---|---|---|
| name() | String | 空 | 定义参数名称 |
| value() | String | 空 | 定义参数简单描述 |
| defaultValue | String | 空 | 定义参数默认值 |
| allowableValues | String | 空 | 定义参数取值范围 |
| required | boolean | false | 定义参数传递必要性 |
| access() | String | 空 | 定义参数访问规则 |
| allowMultiple() | boolean | false | 定义参数能否接收多个数值 |
| example() | String | 空 | 定义参数单个示例 |
| hidden() | boolean | false | 定义参数显隐 |
定义：
该属性就是描述接口中参数的名称。
使用方法：
在 ApiParam 注解中声明 name 的值即可。例如，对于用户接口而言，在本例中，需要传递的参数是一个 user 对象，所以我们需要将 name 的值写为 'user’就可以了，这样，我们就能很清楚的知道，这个接口方法中传递的参数是一个 user 对象了，如下代码段所示（现在你不需要理解业务代码代表什么意思，重点看接口方法上使用的注解及属性即可，下同）。
@ApiParam(name = "user")public User login(User user){// 用户登录业务逻辑}
代码解释：
第1行，我们在 login 接口方法的上方使用了 @ApiParam 注解的 name 属性来描述该接口中的参数名称。
显示结果：
可以看到，在 Parameters 内容区中用红框圈起来的 Parameter 参数的名称就是我们使用 name 属性来描述的接口参数名称。
Tips ：
在实际开发工作中，name 属性的值一般都是根据接口方法中的形参来描述，即接口方法中默认声明的参数名称，除非有特殊说明才可以描述与形参名称不同的值。
如果我们没有使用 name 属性来描述参数的名称，则参数名称默认为接口中自带的参数名称。
定义：
该属性就是对接口中的参数做一个简要的描述，即来说明接口中的参数是用来做什么的。
使用方法：
在 ApiParam 注解中声明 value 的值即可，如果没有描述则默认值为空。例如，就用户接口而言，该接口中的参数是一个用户对象，则我们可以在 value 属性中添加这样的描述：'用户对象，用于用户登录检测，必传’，如下代码段所示。
@ApiParam(name="user", value = "用户对象，用于用户登录检测，必传")public User login(User user){// 用户登录业务逻辑}
代码解释：
第1行，我们在 login 方法的上方使用了 @ApiParam 注解的 name 属性和 value 属性来对接口方法中的 user 参数做一个简单必要的说明。
显示结果：
我们可以看到在 Parameters 内容区域的 Description 红框圈起来的地方并没有显示出我们使用 value 属性所描述的信息，从某种意义上（Swagger 源码角度）讲，这是 Swagger-UI 的一个 Bug ，但是从使用角度来讲可能就是我们用错了 @ApiParam 注解。
如果我们想在 Description 中显示我们所描述的信息，我们又该怎么做呢？
在本节的开篇中，就已经说明了 @ApiParame 既可以写在接口方法的上方，也可以写在接口中参数的位置，在上图中我们是把注解写在了接口方法的上方，那么现在我们来看一下，将注解写在接口中参数的位置时又是一种什么效果吧：
public User login(@ApiParam(name="user", value = "用户对象，用于用户登录检测，必传") User user){// 用户登录业务逻辑}
代码解释：
第1行，我们修改了 @ApiParam 注解的位置，把注解写到了和接口参数相同的位置，通过这种方式来对 user 参数做一个简单必要的说明。
显示结果：
我们可以看到，在 Parameters 内容区域的 Description 位置，已经显示出了我们使用 value 来对 user 参数所描述的信息，上述两种使用 value 的情况请同学们特别注意。
Tips ：
value 属性用于描述接口中字段的说明，一般是一些必要的重要信息，不要描述很长的一段话，如果是一般简单性的描述，那还是不要写出来为好。
出于国人习惯的考虑，在描述 value 属性的值时，尽量使用中文来描述，这样可以做到显而易见、通俗易懂。
鉴于 value 属性的特殊情况，同学们在使用时应该注意：如果接口的方法参数就一个且该参数很好理解，这种情况就在接口方法的上面描述；如果接口的方法参数不便于理解，这种情况就要在接口的方法位置来描述，请同学们根据情况合理使用。
定义：
该属性就是对接口方法中的参数默认值进行描述，即对接口中存在默认值的参数进行简单的描述。
使用方法：
在 ApiParam 注解中，声明 defaultValue 的值即可，如果没有描述则默认值为空。例如，如果我想对用户接口方法中的 user 对象参数中的一个属性，添加默认值描述，那么我可以这样写 defaultValue = “ admin ”(严格来讲，user 参数的默认值应该是一个 json 串，这里为了演示就简单描述了)，如下代码段所示。
public User login(@ApiParam(defaultValue = " admin") User user){// 用户登录业务逻辑}
代码解释：
第1行，我们在 login 接口方法的上方使用了 @ApiParam 注解的 defaultValue 属性来对用户登录接口中存在默认值的属性进行描述。
defaultValue 属性并没有直接的界面显示效果，这个作用效果可以在使用 swagger-ui 进行接口调试的时候可以很直观的看到。
当我们在传递某一参数时，如果我们没有给该参数填充数据，同时该参数被 defaultValue 属性所描述，此时该参数的数据就会变为 defaultValue 属性所描述的值了。这一点在如何使用 swagger-ui 进行接口调试小节中会详细介绍。
Tips ：
defaultValue 属性不要滥用，其用于对接口方法中存在默认值的参数进行说明，如果在接口方法中不存在有默认值的参数，那就不要使用该属性。
如果一个接口方法中存在多个有默认值的参数需要说明，那么请使用 @ApiParam 注解的 defaultValue 属性来对参数分别进行说明。
定义：
该属性就是对接口方法中参数传递的必要性做一个约定，即接口方法中的参数哪些是必须传递的，哪些是非必须传递的。
使用方法：
在 ApiParam 注解中，声明 required 的值即可，如果没有描述则默认值为 false ， 即参数为非必须传递。例如，如果我想把用户登录接口方法中的参数描述为必须传递，那么我可以这样写 required = true，如下代码段所示。
public User login(@ApiParam(required = true) User user){// 用户登录业务逻辑}
代码解释：
第1行，我们在 login 接口方法的上方使用了 @ApiParam 注解的 required 属性来将用户登录接口中的属性描述为必须传递。
如果想要看到 required 属性的作用效果，就需要我们改变浏览器地址栏的路径了：在浏览器地址栏中输入：swagger-ui 访问路径 + /v2/api-docs（至于为什么是这个路径，在后面的文章中会详细说明），在输入完上述 url 之后我们会看到一个由多个 json 串所组成的界面，而这些 json 串的内容正是我们所写的接口。
显示结果：
可以看到，我在用户登录接口的 json 串中用红框圈起来的就是我们使用 required 所描述的结果了。
定义：
该属性就是对接口方法中的参数的可取值范围进行描述。
使用方法：
在 ApiParam 注解中，声明 allowableValues 的值即可，如果没有描述则默认值为空，值得注意的是，使用该属性需要遵循特性的描述格式。例如，如果我想把用户登录接口方法中的参数描述为必须传递，那么我可以这样写 required = true，如下代码段所示。
public User getUserInfo(@ApiParam(allowableValues = "range[1,10]") int userId){// 获取用户信息业务逻辑}
代码解释：
第1行，我们在 getUserInfo 接口方法的上方使用了 @ApiParam 注解的 allowableValues 属性来对用户 id 值的可取范围做一个限制。
当我们以上述接口方法的形式来使用 allowableValues 属性时并不能在 swagger-ui 界面看到任何效果，这应该是 swagger-ui 的一个 bug ，至于使用效果如何，请看后面使用 swagger-ui 进行接口调试小节的内容。
Tips ： 在实际项目开发工作中，allowableValues 使用的频率并不是很高，一般都是为了避免参数传递不合法才设置该属性。
以上是对 ApiParam 注解中经常使用的五个属性进行的详细介绍，name , values , defatluValue , required , allowableValues 掌握这五个属性的使用搭配习惯是真正用好 ApiParam 注解的重要前提。在学习这五个属性时，大家应该结合 ApiOperation 注解来对比并总结它们之间的差异，通过不断的使用来发现它们的使用规律，这一点很重要。
在详细讲解完 ApiParam 重要属性之后，下面我将针对，在 ApiParam 注解中使用频率不是很高，但是有时也会用到的一些属性做概要性讲解，这些属性分别是：access、allowMultiple、example、hidden 。
定义：
example() 属性就是描述接口方法中的一个参数的示例值。
hidden() 属性就是控制接口方法中的参数在 Swagger 界面中的显隐性。
使用方法：
example() 属性默认值为空，当我们需要对接口中的方法添加示例值描述时，可以使用该属性进行描述。例如，对于获取用户信息方法而言，需要传递的参数为用户的 id ，则我可以描述一个示例值为 1。
hidden() 属性允许我们在 Swagger 生成的接口列表界面上，控制接口方法中的参数是否需要显示，默认值为 false，即接口方法中的参数显示，为true时则接口方法中的参数不显示，如下代码段所示。
public User getUserInfo(@ApiParam(example = "1") int userId, @ApiParam(hidden = true) String username){// 获取用户信息业务逻辑}
代码解释：
第1行，我们在 getUserInfo 接口方法中对 userId 参数通过 example 属性描述了示例值，对 username 进行了隐藏。
Tips ：
接口方法中参数的显隐控制应该根据特定安全策略和特定客户需求来决定显隐，不能无故隐藏接口参数，更不能频繁的切换接口参数的显隐。
在实际工作中，应该根据业务要求来合理描述接口中参数的示例值，不能随便描述，更不能描述不清楚。
以上则是 ApiParam 注解中的辅助使用属性的概要介绍，对于剩下的 access、allowMultiple 属性在实际项目开发中几乎很少使用，在这里就不再介绍了，如果大家感兴趣可以去 Swagger 的官网查询相关资料来了解。
本小节对 Swagger 中另一个最经常使用的 ApiParam 注解及其该注解的各个属性做了详细的讲解，针对 ApiParam 注解中经常在实际项目开发中使用的属性采用图文并茂的方式进行了重点介绍和应用剖析，对于一些在实际项目开发中使用基本很少的注解做了概要讲解。
在学习 @ApiParam 注解及其属性时，各位同学应该对比 @ApiOperation 注解及其属性之间的使用差异，通过差异比较总结出适合自己的使用规律和使用方法才是最重要的。
联系客服
