Swagger-ApiOperation 注解

1. 前言

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

ApiOperation 注解在 Swagger 中扮演着非常重要的角色，基本上只要使用 Swagger 那就必须要用 ApiOperation 注解。

重点讲解的属性：value 、tags 、notes ;
概要讲解的属性：httpMethod、nickname、protocols、hidden、code。

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

2. 什么是 ApiOperation 注解？

在我们日常工作中，后端小伙伴们经常会写一些接口，为了方便让大家知道这些接口的功能作用，我们就需要给接口添加一些具体的描述信息，为此，在 Swagger 中，我们就需要使用 ApiOperation 注解来描述我们写的接口。

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

下面我们来看一下 ApiOperation 注解中都包括哪些主要属性。（注意：我们只介绍还在使用的属性，那些被 Swagger 官方已经废弃的属性不再介绍）。

3. ApiOperation 注解主要属性汇总

4. 属性详解

4.1 value () 属性

定义：

该属性就是描述接口的作用是什么，即接口是用来干什么的。

使用方法：

在 ApiOperatio 注解中声明 value 的值即可。例如，就用户登录接口而言，只需要将 value 的值写为 ‘用户登录’就好了，这样我们就能很清楚的知道这个接口就是来做用户登录用的，如下代码段所示（现在你不需要理解业务代码代表什么意思，重点看方法上使用的注解及属性即可，下同）。

@ApiOperation(value = "用户登录")
public CommonResponse<User> userLogin(HttpSession session, @RequestBody User user){
    return userService.login(session, user);
}

代码解释：

第 1 行，我们在 userLogin 方法的上方使用了 @ApiOperation 的 value 属性来描述接口的作用。

显示结果：

在结果显示界面的右上角就是我们使用 value 属性描述的信息（用户登录）。

Tips ： 项目中的接口文档可能需要看的人很多，不只是开发人员看，客户有时候也要看，所以 value 属性值的描述，应该本着通俗易懂的原则进行，一定要根据接口方法实现的具体业务内容来描述，不能随便描述，不能使用表意不清楚的词语来描述，更不能使用专业术语来描述。

4.2 tags () 属性

定义：

该属性就是对实现相同业务场景的接口做一个分组。

使用方法：

在 ApiOperatio 注解中声明 tags 的值即可，如果没有描述则默认值为空。例如，就用户登录接口而言，该接口属于用户业务分组中，所以我们将 tags 的值描述为‘用户’或者‘user’，这样我们就能很清楚的看到这个接口是属于用户业务组的，如下代码段所示。

@ApiOperation(tags = {"user"})
public CommonResponse<User> userLogin(HttpSession session, @RequestBody User user){
    return userService.login(session, user);
}

代码解释：

第 1 行，我们在 userLogin 方法的上方使用了 @ApiOperation 注解的 tags 属性来描述接口所属的业务分组。

显示结果：

我们可以看到在顶部有一个 user 字样，这个就是我们规定的分组名称，也就是 tags 里写的 user 了。

Tips：

1. 在实际项目开发工作中，往往一个接口可能涉及多个业务，这种情况需要我们对接口进行多个分组，而 tags 属性的类型是字符串类型的数组，可以描述一个或多个值，如存在多值时，应该使用如下方法来描述。
2. tags 属性值的描述规则同上述 value 属性。

@ApiOperation(tags = {"user", "customer"})

4.3 notes () 属性

定义：

该属性就是对接口方法做进一步详细的描述。

使用方法：

在 ApiOperatio 注解中声明 notes 的值即可，如果没有描述则默认值为空。例如，如果我想添加对用户登录接口的详细描述信息，那么我可以这样写 notes = “用户登录接口必须是 post 请求”，这种使用效果会直接显示在接口面板中，当做接口的主要内容进行显示，如下代码段所示。

@ApiOperation(notes = {"用户登录接口必须是post请求"})
public CommonResponse<User> userLogin(HttpSession session, @RequestBody User user){
    return userService.login(session, user);
}

代码解释：

第 1 行，我们在 userLogin 方法的上方使用了 @ApiOperation 注解的 notes 属性来进一步描述接口的详细信息。

显示结果：

在我用红框圈起来的地方我们可以看到 Implementation Notes 下放就是我们对该接口的进一步详细描述，其显示在了接口的主要内容区域里面。

Tips ：

1. notes 属性一般用来描述接口的一些必要详细信息，如果是一般的信息则最好不要使用 notes 去描述。
2. 使用 notes 属性来进一步详细描述接口这一行为往往在项目开发中不是必须的。

阶段小结（一）

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

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

4.4 httpMethod () 和 nickname () 属性

定义：

httpMethod () 属性就是对接口的请求类型进行一个约定，常用的接口类型有：“GET”, “HEAD”, “POST”, “PUT”, “DELETE”, “OPTIONS”。

nickname () 属性是为接口起一个别名，方便前后端沟通使用。

使用方法：

httpMethod () 属性默认值为空，但是 Swagger 在处理时会默认获取项目所采用的接口请求类型，我们可以不用专门设置，如果一定要设置该属性，则只允许设置 http 协议规定的属性，不能随意设置。

nickname () 属性允许我们为接口设置一个别名，在设置别名之后，我们设置的别名会出现在浏览器地址栏中，如下代码段所示（httpMethod () 属性自动获取值，这里不再演示）。

@ApiOperation(nickname = "userLoginNickName")
public CommonResponse<User> userLogin(HttpSession session, @RequestBody User user){
    return userService.login(session, user);
}

代码解释：

第 1 行，我们在 userLogin 方法的上方使用了 @ApiOperation 注解的 nickname 属性来为接口起一个别名。

显示结果：

在我用红框圈起来的地方我们可以看到 userLoginNickName 字样，这就是我们为接口所设置的别名。

Tips ：

1. 不要随意定义接口的别名，要根据特定业务场景来设置。
2. 在项目前后端联合测试过程中，给接口起一个别名更方便前后端开发人员的沟通，并没有其他特殊意义。

4.5 protocols ()、hidden () 和 code () 属性

定义：

protocols () 属性就是对接口所使用的网络协议进行一个约定，常用的网络协议有：http、https。

hidden () 属性就是控制接口在 Swagger 界面中的显隐性。

code () 属性就是控制接口的返回状态，常见的有：200，201，404，500 等。

使用方法：

protocols () 属性默认值为空，但是 Swagger 在处理时会默认获取项目所采用的网络协议，我们可以不用专门设置，如果一定要设置该属性，则只允许设置 http 协议规定的属性，不能随意设置，http, https, ws, wss 这些都是被允许的。

code () 属性一般不用特定设置， Swagger 会自动生成接口返回状态，这里不再演示。

hidden () 属性允许我们在 Swagger 生成的接口列表界面上控制接口是否需要显示，默认值为 false，即接口显示，为 true 时则接口不显示，如下代码段所示。

@ApiOperation(hidden = true)
public CommonResponse<User> userLogin(HttpSession session, @RequestBody User user){
    return userService.login(session, user);
}

代码解释：

第 1 行，我们在 userLogin 方法的上方使用了 @ApiOperation 注解的 hidden 属性来隐藏我们的接口。

显示结果：

可以看到在接口列表界面，已经看不到我们的用户登录接口了，这就是当 hidden 属性设置为 true 时所起的作用。

Tips ：

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

阶段小结（二）

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

5. 小结

本小节对 Swagger 中最经常使用的 ApiOperation 注解及其该注解的各个属性做了详细的讲解，针对 ApiOperation 注解中经常在实际项目开发中使用的属性采用图文并茂的方式进行了重点介绍和应用剖析，对于一些在实际项目开发中使用基本很少的注解做了概要讲解。通过这样系统的讲解，希望大家从注解属性的定义到具体使用规范全过程中彻底搞懂 ApiOperation 注解及其注解各属性的语义规则、使用场景、注意事项等。