跳到主要内容

Swagger-Api 注解详解

1. 前言​

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

Api 注解和 ApiOperation 注解一样，在 Swagger 中都扮演着非常重要的角色，Api 注解一般都会配合 ApiOperation 注解一起来使用。

重点讲解的属性：value 、tags 、description ;

概要讲解的属性：consumes、produces、protocols、hidden 。

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

2. 什么是 Api 注解 ？​

Api 注解是作用在接口类上面的注解，其主要是用来给接口类定义相关说明。

Api 注解提供了丰富的属性，来允许我们自定义接口类的描述信息，包括对接口类的简单描述，接口类所属的分组等。

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

3. Api 注解主要属性汇总​

属性名称属性类型默认值作用
value()String空接口类说明
tags()String[]空定义接口类所属分组
description()String空定义接口类的简单描述
protocols()String空网络请求协议
hidden()booleanfalse接口类隐藏
produces()String空接口类请求头类型-输出
consumes()String空接口类请求头类型-输入

4. 属性详解​

4.1 value() 属性​

定义：

该属性就是描述接口类的作用是什么，即同一类下的接口都是用来干什么的。

使用方法：

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

  1. 通过 value 属性来对接口类进行描述的这一行为在实际开发工作中并不常用，各位同学只需要知道有这么一个 value 属性就可以了。
  2. 在实际开发工作中， value 属性经常被 tags 属性所替代，这也是 Swagger 官方所设定的规则：当 Api 注解的 value 属性和 tags 属性同时存在时，tags 属性的值会替代 value 属性的值，这一点需要同学们注意。

4.2 tags() 属性​

定义：

该属性就是对实现相同业务功能的接口类做一个大型的分组，该分组中包括同业务功能下的所有的接口。

使用方法：

在 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”})。

4.3 description() 属性​

定义：

该属性就是对接口类进行简单概要的描述，通常是描述一些注意的地方，value 属性更多的则是描述接口类的用途，这一点同学们要分清。

使用方法：

在 Api 注解中声明 description 的值即可，如果没有描述则默认值为空。例如，如果我想添加对用户接口类的概要描述信息，那么我可以这样写 description = “所有用户业务接口必须使用post请求”，如下代码段所示。

@Api(description = {"所有用户业务接口必须使用post请求"})
public class UserController{
    // do something...
}

代码解释：

第1行，我们在 UserController 接口类的上方使用了 @Api 注解的 description 属性来描述用户接口类的一些注意的地方和约定。

显示结果：

在我用红框圈起来的地方我们可以看到使用 description 注解所描述的信息了。

Tips ：

  1. description 属性一般用来对接口类进行一些注意事项和约定的描述，不要将其描述为接口类的用途。
  2. description 属性在实际开发工作中还是很常用的，所以描述好 description 是体现一个程序员对业务内容是否充分理解的标志。

阶段小结（一）​

以上是对 Api 注解中经常使用的三个属性进行的详细介绍，value，tags，description 这三个属性不管是在项目开发中，还是在需求沟通中，使用的都很频繁，所以真正掌握这三个属性，是用好 Api 注解的重要前提。在学习这三个属性时，大家应该结合 ApiOperation 注解来对比并总结它们之间的差异，通过不断的使用来发现它们的使用规律，这一点很重要。

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

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

  1. 接口类的显隐控制应该根据特定安全策略和特定客户需求来决定显隐，不能无故隐藏接口，更不能频繁的切换接口的显隐。
  2. 在实际工作中，如果需要隐藏接口类则需要和项目组报备情况，说明原因。

阶段小结（二）​

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

5. 小结​

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

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