Swagger-Extension 和 ExtensionProperty 注解

1. 前言

本节会结合一个用户登录接口方法来为大家介绍 Swagger 中的两个关联注解 - Extension 和 ExtensionProperty 及所提供的常用属性。

Extension 和 ExtensionProperty 不能单独使用，需要搭配 @ApiOperation 注解使用，单独使用没有任何效果。

在实际项目中也是很少用到，其提供的属性也是很少，所以我们只需要掌握他们最基本的用法和常用属性即可。

重点讲解的属性：

• Extension 注解的 name 、 properties ；

• ExtensionProperty 注解的 name 、 value 。

2. 什么是 Extension 和 ExtensionProperty 注解 ？

Extension 和 ExtensionProperty 这两个注解属于关联注解，都是用来对接口方法中之外的但是也是和这个方法有关的参数属性进行描述说明，即都是针对接口方法之外但是也和这个方法有关的参数进行补充说明，在 Swagger 中这一类的参数我们称为接口方法拓展参数 (如果对这个概念不理解，请自行查阅)。

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

3. 注解主要属性汇总

Extension 注解

ExtensionProperty 注解

4. 属性详解

4.1 Extension 注解相关属性

name () 和 properties () 属性

定义：

name 属性就是定义拓展参数数组列表的名称，也可以理解为定义拓展参数的名称。

properties 属性就是定义拓展参数的列表，即将拓展参数放到一个数组里面，可以是一个也可以是多个。

使用方法：

name 和 properties 两个属性虽然属于 @Extension 注解，但是 @Extension 注解不能单独拿来使用，需要和 @ApiOperation 注解一起搭配才能使用，因为在 @ApiOperation 注解中存在一个名为 extensions 的属性，其属性的值就是通过 @Extension 注解来描述的。

例如，对于用户登录方法，我想为其添加一个拓展参数，那我们可以这样写：@Extension(name = "用户登录拓展参数", properties = { @ExtensionProperty(name = "userEmail", value = "user email") } )（现在你不需要理解业务代码代表什么意思，重点看所使用的注解及属性即可，下同）。

@ApiOperation(value = "user", 
            extensions = { 
            @Extension(name = "用户登录拓展参数", properties = { 
                    @ExtensionProperty(name = "userEmail", value = "user email") } ) })
public ServerResponse<User> login(User user){
    // do something...
} 

代码解释：

1-3 行，我们在用户登录接口方法的上方通过使用 @ApiOperation 注解来使用 @Extension 注解的 name 和 properties 属性，由于篇幅有限，这里就不给大家截图演示了。

Tips ：

1. 在使用 @Extension 注解及其相关属性时，一定要看清楚该注解是通过哪种方法进行使用的。
2. 在实际项目开发中，一般具体的一个接口很少会出现拓展参数，如果存在，那也是通过业务需求来描述的，我们不能随意编造任何拓展参数。

4.2 ExtensionProperty 注解相关属性

name () 和 value () 属性

定义：

name 属性是用来描述接口方法中每一个拓展参数的名称，即给每一个拓展参数都起一个名字。

value 属性表示每一个接口方法中的拓展参数的具体的值，或者对拓展参数的解释说明。

使用方法：

name 和 value 两个属性的使用方法和 @Extension 注解中属性的使用方法相同，这里还是以 @ApiOperation 注解为例，详细代码使用方法如下。

@ApiOperation(value = "user", 
            extensions = { 
            @Extension(name = "用户登录拓展参数", properties = { 
                    @ExtensionProperty(name = "userEmail", value = "user email") } ) })
public ServerResponse<User> login(User user){
    // do something...
} 

代码解释：

我们可以看到，ExtensionProperty 注解中，属性的使用方法，是通过 @ApiOperation 注解中的 properties 属性来定义的，这里不再赘述。

Tips ：

1. 在使用 ExtensionProperty 注解时，注意是和 @ApiOperaion 注解中的哪个属性进行搭配，其固定的代码方式是什么，这是同学们需要理清的地方。
2. ExtensionProperty 注解的两个属性经常用于指名多个接口方法中的拓展参数，很少会只指名一条，在实际开发中，如果接口方法存在多个拓展参数，那么应该都指名出来才对。

5. 小结

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

在学习 Extension 和 ExtensionProperty 注解及其常用属性时，各位同学需要注解和其他注解搭配的使用方法，因为这两个注解均不能单独拿出来使用。