Swagger-ApiImplicitParam 注解详解

1. 前言

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

ApiImplicitParam 注解经常来配合其他注解一同使用，并不会经常单独拿来使用，所以，对于 ApiImplicitParam 注解，我们只需要了解它的作用和注意事项即可，不必重点掌握。

重点讲解的属性：name 、value 、defaultValue 、 required ；
概要讲解的属性：paramType 、 dataType 。

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

2. 什么是 ApiImplicitParam 注解？

ApiImplicitParam 注解是作用在接口方法上的注解，用来对该接口中的参数进行简短的描述，常常和 ApiParam 注解一起搭配使用。

ApiImplicitParam 注解提供了丰富的属性，来允许我们自定义接口方法中参数的描述信息，包括接口中参数是否必传、参数类型等。

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

3. ApiImplicitParam 注解主要属性汇总

4. 属性详解

4.1 name() 属性

定义：

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

使用方法：

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

@ApiImplicitParam(name = "user")
public ServerResponse<User> userLogin(User user){
    // do something...
}

代码解释：

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

显示结果：

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

Tips ：

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

4.2 value() 和 defaultValue() 属性

定义：

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

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

使用方法：

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

@ApiImplicitParam(value = "user对象，用来接收用户的登录数据")
public ServerResponse<User> userLogin(User user){
    // do something...
}

代码解释：

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

显示结果：

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

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

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

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

4.3 required() 属性

定义：

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

使用方法：

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

@ApiImplicitParam(name = "user", required = true)
public ServerResponse<User> userLogin(User user){
    // do something...
}

代码解释：

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

4.4 paramType() 和 dataType() 属性

定义：

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

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

使用方法：

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

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

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

@ApiImplicitParam(name = "user", paramType = "header", dataType = "User")
public ServerResponse<User> userLogin(User user){
    // do something...
}

代码解释：

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

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

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

阶段小结（二）

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

5. 小结

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

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