Swagger-ApiParam 注解详解

1. 前言

本节会继续结合一个用户登录接口给大家介绍 Swagger 中的另一个核心注解 - ApiParam 注解及所提供的常用属性。

ApiParam 注解一般会结合 ApiOperation 注解以及 Api 注解一起来使用。

重点讲解的属性：name 、value 、defaultValue 、allowableValues 、required ；

概要讲解的属性：access、allowMultiple、example、hidden。

希望大家在学习本节过程中能够分清主次，有的放矢。

2. 什么是 ApiParam 注解？

ApiParam 注解，是可以作用在接口方法上面，以及接口方法中的参数位置的注解，其主要是用来给接口中的参数定义相关参数说明，主要是为了，帮助相关人员理解接口中每个参数的含义。

ApiParam 注解同样也提供了丰富的属性，来允许我们对接口中的参数添加描述信息，包括该参数的具体含义、参数是否必须传递等。

下面我们来看一下 ApiParam 注解中都包括哪些主要属性。

3. ApiParam 注解主要属性汇总

属性名称	属性类型	默认值	作用
name()	String	空	定义参数名称
value()	String	空	定义参数简单描述
defaultValue	String	空	定义参数默认值
allowableValues	String	空	定义参数取值范围
required	boolean	false	定义参数传递必要性
access()	String	空	定义参数访问规则
allowMultiple()	boolean	false	定义参数能否接收多个数值
example()	String	空	定义参数单个示例
hidden()	boolean	false	定义参数显隐

4. 属性详解

4.1 name() 属性

定义：

该属性就是描述接口中参数的名称。

使用方法：

在 ApiParam 注解中声明 name 的值即可。例如，对于用户接口而言，在本例中，需要传递的参数是一个 user 对象，所以我们需要将 name 的值写为 ‘user’就可以了，这样，我们就能很清楚的知道，这个接口方法中传递的参数是一个 user 对象了，如下代码段所示（现在你不需要理解业务代码代表什么意思，重点看接口方法上使用的注解及属性即可，下同）。

@ApiParam(name = "user")
public User login(User user){
    // 用户登录业务逻辑
}

代码解释：

第1行，我们在 login 接口方法的上方使用了 @ApiParam 注解的 name 属性来描述该接口中的参数名称。

显示结果：

可以看到，在 Parameters 内容区中用红框圈起来的 Parameter 参数的名称就是我们使用 name 属性来描述的接口参数名称。

Tips ：

1. 在实际开发工作中，name 属性的值一般都是根据接口方法中的形参来描述，即接口方法中默认声明的参数名称，除非有特殊说明才可以描述与形参名称不同的值。
2. 如果我们没有使用 name 属性来描述参数的名称，则参数名称默认为接口中自带的参数名称。

4.2 value() 属性

定义：

该属性就是对接口中的参数做一个简要的描述，即来说明接口中的参数是用来做什么的。

使用方法：

在 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 ：

1. value 属性用于描述接口中字段的说明，一般是一些必要的重要信息，不要描述很长的一段话，如果是一般简单性的描述，那还是不要写出来为好。
2. 出于国人习惯的考虑，在描述 value 属性的值时，尽量使用中文来描述，这样可以做到显而易见、通俗易懂。
3. 鉴于 value 属性的特殊情况，同学们在使用时应该注意：如果接口的方法参数就一个且该参数很好理解，这种情况就在接口方法的上面描述；如果接口的方法参数不便于理解，这种情况就要在接口的方法位置来描述，请同学们根据情况合理使用。

4.3 defaultValue() 属性

定义：

该属性就是对接口方法中的参数默认值进行描述，即对接口中存在默认值的参数进行简单的描述。

使用方法：

在 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 ：

1. defaultValue 属性不要滥用，其用于对接口方法中存在默认值的参数进行说明，如果在接口方法中不存在有默认值的参数，那就不要使用该属性。
2. 如果一个接口方法中存在多个有默认值的参数需要说明，那么请使用 @ApiParam 注解的 defaultValue 属性来对参数分别进行说明。

4.4 required() 属性

定义：

该属性就是对接口方法中参数传递的必要性做一个约定，即接口方法中的参数哪些是必须传递的，哪些是非必须传递的。

使用方法：

在 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 所描述的结果了。

4.5 allowableValues() 属性

定义：

该属性就是对接口方法中的参数的可取值范围进行描述。

使用方法：

在 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 。

4.6 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 ：

1. 接口方法中参数的显隐控制应该根据特定安全策略和特定客户需求来决定显隐，不能无故隐藏接口参数，更不能频繁的切换接口参数的显隐。
2. 在实际工作中，应该根据业务要求来合理描述接口中参数的示例值，不能随便描述，更不能描述不清楚。

阶段小结（二）

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

5. 小结

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

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