【原】Swagger入门教程（四）

Swagger-Authorization 和 AuthorizationScope注解

1. 前言

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

Authorization 和AuthorizationScope 注解，在实际项目中很少用到，因为这两个注解是和权限有关的，众所周知，和权限有关的框架或者中间件成熟的已经有很多了，而 Swagger 更多的则是用来生成接口在线文档，重点并不在权限控制上，所以我们只需要掌握他们最基本的用法和常用属性即可。

重点讲解的属性：

• Authorization 注解的 value 、scopes 属性；

• AuthorizationScope 注解的 scope 、 description 属性。

2. 什么是 Authorization 和 AuthorizationScope 注解 ？

Authorization 注解是作用在接口方法上的注解，用来对该接口方法的访问权限进行控制，即给该接口方法添加的额外权限是什么，一般不会单独使用，经常和 @ApiOperation 注解或者 @Api 注解搭配使用 。

AuthorizationScope 注解也是作用在接口方法上的注解，作用和 @Authorization 注解类似，他是用来描述接口权限的一个范围，即定义该接口的权限范围是什么。

Authorization 和 AuthorizationScope 注解的关系并不像是一组关系紧密的注解，因为 Authorization 注解可以抛开 AuthorizationScope 注解使用。

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

3. 注解主要属性汇总

Authorization 注解

属性名称	属性类型	默认值	作用
value()	String	空	定义接口权限名称
scopes()	AuthorizationScope[]	@AuthorizationScope(scope = “”, description = “”)	定义接口权限范围

AuthorizationScope 注解

属性名称	属性类型	默认值	作用
scope()	String	空	定义接口权限单独范围名称
description()	String	空	定义接口权限单独范围的描述

4. 属性详解

4.1 Authorization 注解相关属性

value() 属性

定义：

该属性就是对接口访问权限添加一个名称，即接口访问权限的名称是什么。

使用方法：

value 属性的使用方法有些特殊，不能单独使用，因为单独使用时， Swagger 并不会解析该属性，需要和 @ApiOperaion 注解和 @Api 注解一起搭配使用，这样 Swagger 才会解析该注解。

但是使用该属性所描述的值并不会显示在界面上，只会显示一个标志，表明该接口方法具有 Swagger 的权限控制策略，如果想要在界面上调试该接口需要一定的权限。

这里以 @ApiOperaion 注解为例，在 ApiOperaion 注解中直接声明 authorizations 属性的值即可，authorizations 的值是一个 Authorization 类型的数组。

例如，对于用户登录接口，我想添加一个名称为’普通用户可访问'的权限名称，我们可以这样写：authorizations = { @Authorization(value = “普通用户可访问”) （现在你不需要理解业务代码代表什么意思，重点看所使用的注解及属性即可，下同）。

@ApiOperation(value = "userlogin", authorizations = { @Authorization(value = "普通用户可访问") })public ServerResponse<User> login(User user){    // do something...}

代码解释：

1-3 行，我们在用户登录接口方法的上方定义了 ApiOperation 注解的 authorizations 属性，其值为 Authorization 注解的 value 属性所描述。

显示结果：

可以看到，在红色箭头所指的右上角位置有一个锁的图片，这个锁的图片就是我们使用 Authorization 注解的 value 属性所展示的效果了。

Tips ： 在使用 Authorization 注解的 value 属性前需要在 Swagger 的配置类中取配置和权限有关的 schema ，如果不配置的话，就不能对接口进行权限控制，由于本门课程针对 Swagger 初学者，所以这里就不再介绍了，感兴趣的可以自行查阅资料了解。

scopes() 属性

定义：

该属性就是对接口权限的范围做一个描述，即描述该接口都可以允许哪些权限访问，超过这个权限就不能访问该接口。

使用方法：

scopes 属性的使用方法和 value 属性的使用方法相同，这里还以 @ApiOperation 属性为例，详细代码如下所示。

由于 scopes 属性的值是使用 AuthorizationScope 注解来描述，且 AuthorizationScope 注解的使用要求项目中必须要用到 OAuth2 框架，所以 scopes 属性的描述也要求项目中必须要用到 OAuth2 框架，OAuth2 框架的使用不在本门课程内，所以这里就不再演示了。

综上所述，同学们只需要知道这个属性的基本作用和基本用法即可。

@ApiOperation(value = "userlogin", authorizations = { @Authorization(scopes = { @AuthorizationScope(scope = "普通用户", description = "common user") } })public ServerResponse<User> login(User user){    // do something...}

代码解释：

1-3行，我们在用户登录接口方法的上方定义了 ApiOperation 注解的 authorizations 属性，其值为 Authorization 注解的 scopes 属性所描述。

Tips ： 在实际项目开发中，如果非要使用 Authorization 注解的 scopes 属性来对接口进行权限控制，那么项目中必须要有 OAuth2 框架，但是往往此框架可以直接对接口进行权限控制，不需要再使用该注解进行配置了。

4.2 AuthorizationScope 注解相关属性

scope() 和 description() 属性

定义：

scope 属性是用来描述访问接口的权限的具体的一个范围名称，即描述接口访问的单个权限名称。

description 属性就是对这个单个的权限名称做一个简短的描述，来解释说明这个权限所代表的意思。

使用方法：

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

@ApiOperation(value = "userlogin", authorizations = { @Authorization(scopes = { @AuthorizationScope(scope = "普通用户", description = "common user") } })public ServerResponse<User> login(User user){    // do something...}

代码解释：

我们可以看到，AuthorizationScope 注解中属性的使用方法代码和 Authorization 中的是完全相同的，这就说明：如果想对接口方法定义访问权限范围，则必须要使用 AuthorizationScope 注解才行，这里不再赘述。

Tips ：

1. 在使用 AuthorizationScope 注解时，注意和 @ApiOperaion 注解的搭配，代码格式稍微有些绕，同学们在学习时需要理清楚代码格式。

2. AuthorizationScope 注解的两个属性经常用于在接口权限存在多条时使用，一般很少单独使用。

5. 小结

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

无论是 Authorization 注解，还是 AuthorizationScope 注解，都是用来对接口的控制访问权限添加额外的描述，而且 AuthorizationScope 注解中属性的使用还需要项目中必须用到 OAuth2 框架，所以我建议：项目中如果需要对接口添加访问权限控制，那就直接使用权限控制框架就好了。

在学习 Authorization 和 AuthorizationScope 注解及其常用属性时，各位同学注意斟酌这两个注解和权限控制框架之间的差异，要能够做到什么时候使用注解合适，什么时候使用权限控制框架合适。

Swagger-SwaggerDefinition 注解

1. 前言

本节会继续结合一个用户接口相关类来给大家介绍 Swagger 中的另一个注解  SwaggerDefinition 注解及所提供的常用属性。

SwaggerDefinition 注解在实际开发中用的非常少了，尽管他提供了很多属性，但是在绝大多数情况下可以通过配置类解决的问题都不会用 SwaggerDefinition 注解。

所以大家在学习 SwaggerDefinition 注解的时候，只需要掌握基本定义和基本用法即可，由于篇幅有限，我只会选取最重要的属性来给大家截图演示，那些基本不用的就不再截图演示了。

重点讲解的属性：host 、basePath 、tags 、 externalDocs 。

2.  什么是 SwaggerDefinition 注解 ？

SwaggerDefinition 注解是作用在接口类上面的注解，其主要是用来给 Swagger 生成的 UI 界面（下称 swagger-ui 界面）做一些额外的描述。

SwaggerDefinition 注解提供了丰富的属性来允许我们自定义 swagger-ui 界面的描述信息，包括界面访问地址、界面版本等。

下面我们来看一下 SwaggerDefinition 注解中都有哪些常用的属性。

3. SwaggerDefinition 注解主要属性汇总

属性名称	属性类型	默认值	作用
host()	String	空	swagger-ui 界面访问主机
basePath()	String	空	接口访问基本路径
tags()	Tag[]	@Tag(name = “”)	定义全局接口分组类型
externalDocs()	ExternalDocs	@ExternalDocs(url = “”)	定义接口中参方法或参数额外描述文档地址

4. 属性详解

4.1 host() 和 basePath() 属性

定义：

host 属性就是描述 swagger-ui 界面的访问主机，或者说是 Ip 地址，即如果，我想访问 Swagger 为我们生成的 swagger-ui 界面，所需要在浏览器地址栏中输入的地址信息。

basePath 属性就是描述 swagger-ui 界面的完整访问地址，他需要依赖 host 属性。

使用方法：

在 SwaggerDefinition 注解中，声明 host 和 basePath属性的值即可。

例如，我想让 swagger-ui 界面在本地就可以访问，那么我们可以这样描述 host 属性：host = “localhost”, 而 basePath 属性可以这样描述：basePath = “localhost:9001”，这样我们就能很清楚的知道 swagger-ui 界面所在的位置了（现在你不需要理解业务代码代表什么意思，重点看接口类上使用的注解及属性即可，下同）。

@SwaggerDefinition(host = "localhost", basePath = "localhost:9001")public class UserController{    // do something...}

代码解释：

第 1 行，我们在 UserController 用户接口类的上方，使用了 @SwaggerDefinition 注解的 host 属性和 basePath 属性来规定 swagger-ui 界面的生成位置。

显示结果：

可以看到，在用红框圈起来的地方，就是我们使用 host 属性和 basePath 属性所描述的 swagger-ui 界面的访问路径了。

Tips ：

1. host 属性和 basePath 属性的区别在于：前者只是定义了 swagger-ui 界面的访问 Ip 地址，如果没有端口的限制，则可以直接访问；而后者则是定义了 swagger-ui 界面的完整位置，其中就包括了端口的存在。

2. 在实际开发工作中，往往不需要使用这两个属性来专门的定义 swagger-ui 的访问路径，因为 Swagger 会默认获取项目中通过配置类来定义的地址信息，使用这两个属性就多此一举了。

4.2 tags() 属性

定义：

该属性就是对项目中所有的接口，添加分组类型描述，即在全局层面定义接口的所属分组类型，类似于 @Api 和 @ApiOperaiton 注解中的 tags 属性。

使用方法：

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

@SwaggerDefinition(tags = { @Tag(name = "user") })public class UserController{    // do something...}

代码解释：

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

Tips ： 该属性在实际工作中基本很少使用，如果有的接口需要进行分组，那么可以直接使用 @Api 注解的 tags 属性来描述，大家只需要知道 SwaggerDefinition 注解存在一个 tags 属性即可。

4.3 externalDocs() 属性

定义：

如果接口方法或其中的参数存在额外的文档描述，则可以通过该属性进行绑定，即为接口方法或其中的参数提供额外的文档支持。

使用方法：

在 SwaggerDefinition 注解中声明 externalDocs 的值即可。例如，如果我想添加一个额外的文档地址，那么我可以这样写 externalDocs = @ExternalDocs(url = “localhost:8000”)，如下代码段所示。

@SwaggerDefinition(externalDocs = @ExternalDocs(url = "localhost:8000"))public class UserController{    // do something...}

代码解释：

第 1 行，我们在 UserController 接口类的上方使用了 @SwaggerDefinition 注解的 externalDocs 属性来描述额外文档的地址信息。

Tips ： externalDocs 属性很少使用，在实际工作中，如果有的接口方法和接口方法中的参数有其他额外的描述话，就直接使用 @ApiOperation 来一并说明了，并不会单独使用一个注解再来说明。

5. 小结

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

SwaggerDefinition 虽是 Swagger 众多注解中的一个注解，但在实际开发工作中其存在的价值值得我们重新考量。

Swagger-Info、Contact、License 注解

1. 前言

本节会结合一个用户相关接口类来为大家介绍 Swagger 中的三个小注解 - Info、Contact、License 注解及所提供的常用属性。

Info、Contact、License 这三个注解均不能单独使用，都需要搭配其他注解才能使用，鉴于篇幅有限，所以这里就不再对搭配使用的注解逐一介绍了。

对于这三个小注解，我们只需要了解他们分别代表什么含义，以及他们都有哪些属性，属性的作用都是什么就可以了。

重点讲解的属性：

• Info 注解的 title 、 version 、 description ；

• Contact 注解的 name 、 url 、 email ；

• License 注解的 name 、 url。

2. 什么是 Info、Contact、License 注解 ？

Info 、Contact 、License、三个注解都是作用在接口类上的注解，用来对 swagge-ui 界面上的一些信息进行描述，一般都不会单独使用，经常和 @SwaggerDifinitiion 注解搭配使用，他们的不同点在于：

Info 注解是对 swagger-ui 界面上的基本信息进行描述，包括但不限于界面的标题、界面的介绍等。

Contact 注解是对 swagger-ui 界面上的一些和接口有关的联系人的信息进行描述，包括但不限于开发人员名称、地址等。

License 注解是对 swagger-ui 界面上的一些和接口有关的服务条款或者使用的开源协议进行描述，包括服务名称、服务所在地址。

下面我们来看一下上述三个注解中都包括哪些常用属性。

3. 注解主要属性汇总

Info 注解

属性名称	属性类型	默认值	作用
title()	String	空	定义界面标题名称
version()	String	空	定义界面版本
description	String	空	定义界面介绍

Contact 注解

属性名称	属性类型	默认值	作用
name()	String	空	定义联系人名称
url()	String	空	定义联系人主页
email	String	空	定义联系人邮箱

License 注解

属性名称	属性类型	默认值	作用
name()	String	空	定义服务条款名称
url()	String	空	定义服务条款地址

4. 属性详解

4.1 Info 注解相关属性

title() 、version() 、 description() 属性

定义：

title() 属性就是对界面的标题做一个描述，即描述界面的标题叫什么。

version() 属性就是对界面的版本做一个描述，通常这个版本指的是接口文档的版本，即描述当前接口文档属于什么版本。

description() 属性就是对界面做一个简单扼要的介绍，即用来描述界面是用来干什么的或者一些其他的注意事项等。

使用方法：

上述三个属性均可以在 Info 注解中注解声明，具体使用方法请看如下代码：(现在你不需要理解业务代码代表什么意思，重点看所使用的注解及属性即可，下同）。

@SwaggerDefinition(info = @Info(title = "慕课网 Wiki 教程", version = "1.0", description = "此界面为慕课网 Wiki-Swagger 教程界面"))public class UserController {    // do something...}

代码解释：

1-3 行，我们在用户相关接口类的上方定义了 Info 注解的 title 、 version 、 description 属性，由于篇幅有限，这里就不截图演示了。

Tips ： Info 注解的使用方法我们可以看到是搭配 @SwaggerDefinition 注解的，在实际项目开发中，Info 注解很少使用，所以大家只要了解基本定义和基本用法即可。

4.2 Contact 注解相关属性

name() 、url() 、email() 属性

定义：

name 属性就是用来描述开发或者配置这个界面的开发者或者管理员的名称，一般是指系统开发人员的名称。

url 属性就是对通过 name 属性所描述的人的进一步介绍信息，如果这个人有个人博客或者其他网站介绍的话，都可以通过该属性进行指名。

email 属性就是描述 name 属性所描述的人的邮箱地址，即这个人的邮箱地址是什么。

使用方法：

name 、 url 、 email 属性都可以直接在 Contact 注解中直接声明来使用，具体使用方法请看下述代码：

@SwaggerDefinition(info = @Info(title = "慕课网 Wiki 教程", version = "1.0", description = "此界面为慕课网 Wiki-Swagger 教程界面",contact = @Contact(name = "Steafan_" , url = "暂无", email = "保密")))public class UserController {    // do something...}

代码解释：

1-3 行，我们在 SwaggerDefinition 注解的 info 属性中使用了 contact 属性，并将其值描述为 @Contact 注解的相关属性，这就是 @Contact 注解及其属性的使用方法，由于篇幅有限，这里就不截图演示了。

Tips ：

1. 在实际项目开发功能中，name 属性的值可以是任意名称，只要在有问题时可以查询到这个人是谁就可以了。

2. email 属性的值一般都是具体人的真实邮箱了，因为很多公司是通过邮件的方式来进行问题的沟通。

3. url 属性的值一般指的就是具体人的个人技术博客，或者自建的个人网站等，通过这种方式可以全方面了解这个人的技术水平。

4.3 License 注解相关属性

name() 、url() 属性

定义：

name 属性就是用来描述界面上，具体来讲是系统中所使用的服务条款、开源协议等。

url 属性就是用来描述其服务条款或开源协议所引用的地址信息。

使用方法：

name 、 url 属性都可以直接在 License 注解中直接声明来使用，具体使用方法请看下述代码：

@SwaggerDefinition(info = @Info(title = "慕课网 Wiki 教程", version = "1.0", description = "此界面为慕课网 Wiki-Swagger 教程界面",contact = @Contact(name = "Steafan_" , url = "暂无", email = "保密"),license = @License(name = "慕课网 Wiki 教程服务条款", url = "还在建设中，敬请期待")))public class UserController {    // do something...}

代码解释：

2-4 行，我们在 SwaggerDefinition 注解的 info 属性中，使用了 license 属性，并将其值描述为 @License 注解的相关属性，这就是 @License 注解及其属性的使用方法，由于篇幅有限，这里就不截图演示了。

Tips ： 只要项目中存在引用了外部服务条款或者开源协议的情况，无论使用规模多少，都应该用 @License 注解的相关属性表明，以免由于版权问题引起不必要的纠纷。

5. 小结

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

Info、Contact、License 这三个注解其实并没有太大的作用，因为这三个注解在项目中所起的作用通过一个 Swagger 配置类即可完成，而且配置类在配置起来还相对灵活，所以我建议：如果项目中需要配置 swagger-ui 界面的描述信息，请综合考虑之后再决定是采用配置类的形式还是采用注解的形式。

在学习 Info、Contact、License 注解及其常用属性时，各位同学注意注意区分这三个注解的不同之处，理清在不同场景下应该如何应用这三个注解的关系就可以了。

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 注解

属性名称	属性类型	默认值	作用
name()	String	空	定义拓展参数数组列表名称
properties()	ExtensionProperty[]	空	定义拓展参数数组列表

ExtensionProperty 注解

属性名称	属性类型	默认值	作用
name()	String	空	定义具体拓展参数名称
value()	String	空	定义具体拓展参数说明

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 注解及其常用属性时，各位同学需要注解和其他注解搭配的使用方法，因为这两个注解均不能单独拿出来使用。

Swagger - 注解组合实战

1. 前言

写到这里呢，在 Swagger 中的注解及其属性都给大家介绍完毕了，那么我们现在需要掌握的就是在真正的项目中对这些注解进行实操，达到真正会使用的目的。

在前面所讲课程中，课程内容都是针对 Swagger 中的一个注解进行介绍，并不会介绍各个注解间都有一个什么样的关系，以及各个主键间如何搭配或者配合使用。

针对上述问题，本节会结合几个在 Swagger 中使用频率非常高的注解进行组合式讲解，无论是两个注解间的搭配使用，还是多个注解间的配合使用，我都会在本节中进行详细介绍，小伙伴们赶快打击精神来学习吧！

本节会结合以下几个常用注解进行组合实战讲解：

• @Api 注解；

• @ApiOperation 注解；

• @ApiParam 注解；

• @ApiImplicitParams 注解；

• @ApiResponses 注解；

• @ApiModel 注解；

• @ApiModelProperty 注解。

本节主要内容有：

• @Api 注解与 @ApiOperation 注解组合实战；

• @ApiParam 注解与 @ApiImplicitParams 注解组合实战；

• @ApiModel 注解与 @ApiModelProperty 注解组合实战；

• @ApiImplicitParams 注解与 @ApiResponses 注解组合实战。

希望大家在学习本节过程中能够真正掌握多个注解间配合使用的方法，做到融会贯通，随手拈来。

2. @Api 注解与 @ApiOperation 注解组合实战

实操目标： 实现接口类与接口类中所有接口方法的准确描述。

实现思路：

第一步：使用 @Api 注解对接口类进行描述。

第二步：使用 @ApiOperation 注解对接口类中所有接口方法进行描述。

第三步：查看配置结果。

实现代码：

接口类：

@Api(value = "user-controller", description = "用户业务相关接口类", tags = {"user"})public class UserController{    // do something...}

代码解释：

第 1 行，我们在接口类的上方使用 @Api 注解的 value 属性和 description 属性以及 tags 属性为接口类添加了一些文字描述信息来对接口类进行一些必要的描述。

其中，value 属性表示接口类在 Swagger 界面上所显示的名称，description 表示对接口类的描述，tags 属性则表示对该接口类添加一个分组，表明该接口类是属于哪一组的。

实现代码：

接口方法：

@ApiOperation(name = "user", value = "用户登录对象", tags = {"user"})public ServerResponse<User> login(HttpSession session, User user){    // do something...}

代码解释：

第 1 行，我们在接口方法上使用 @ApiOperation 注解的 name 和 value 属性来对接口方法中的参数进行说明，使用 tags 属性来对该接口方法进行一个分组。

显示结果：

可以看到，在第一个标签的位置，从左到右分别表示对该用户相关接口类的分组名称 user ， 以及对该用户接口类的说明：'用户相关接口类’。

在第二个标签位置，表示对用户登录接口方法中的 user 对象类型的参数的说明：'用户登录对象’。

Tips ：

1. 如果在一个接口类中，我们使用了 @Api 注解的 tags 属性来对该接口分组，那么该接口类中的所有接口都将默认被分到该类中，除非我们使用 @ApiOperation 注解的 tags 属性为接口方法重新指定了另外一个分组。

2. 在实际项目开发中，@ApiOperation 注解与 @Api 注解经常这样搭配起来用，可以说，只要使用 Swagger 那么必定会这么用，这种使用方法同学们必须掌握。

3. 不同版本的 Swagger 显示可能会有不同，这点请同学们注意。

3. @ApiParam 注解与 @ApiImplicitParams 注解组合实战

实操目标： 实现对接口方法中多个参数的准确描述，同时体会 @ApiParam 注解与 @ApiImplicitParams 注解使用时的差异。

实现思路：

第一步：使用 @ApiParam 注解对接口方法中的一个参数进行描述，并查看其描述结果。

第二步：使用 @ApiImplicitParams 注解对接口方法中的多个参数进行描述，并查看其描述结果。

第三步：总结对比两个注解使用时的差异。

实现代码：

@ApiParam 注解作用在接口方法上时：

@ApiParam(name = "session", value = "用户session数据")public ServerResponse<User> login(HttpSession session, User user){    // do something...}

显示结果：

可以看到，在红色框框起来的位置并没有看到关于 session 参数的说明 (正常的话会在红框中出现对 session 参数的说明)。

• @ApiImplicitParams 注解作用在接口方法上时 

@ApiImplicitParams(value = { @ApiImplicitParam(name = "session", value = "用户session数据"),@ApiImplicitParam(name = "user", value = "用户登录对象参数") })public ServerResponse<User> login(HttpSession session, User user){    // do something...}

可以看到，在用红色框框起来的位置分别显示出了使用 @ApiImplicitParams 注解对参数所描述的信息，并且是多个参数。

Tips ：

1. 如果你使用的是 Swagger 的低版本且只需要对接口中的一个参数进行描述，则可以使用 @ApiParam 注解；如果你使用的是 Swagger 高版本且需要对多个接口中的参数进行描述，则应该首先考虑使用 @ApiImplicitParams 注解。

2. 在实际项目开发中，如果需要对接口中的参数进行描述，那么无论需要描述几个参数，都应该首先考虑使用 @ApiImplicitParams 注解，因为他的兼容性是最好的。

3. 在 Swagger 高版本中，@ApiParam 注解并不会有任何效果，而 @ApiImplicitParams 注解则替代了 @ApiParam 注解的作用效果，并且支持对多个参数同时进行描述，这点需要同学们注意。

4. @ApiModel 注解与 @ApiModelProperty 注解组合实战

实操目标： 以用户实体类为例，实现对用户业务实体 (Entity) 的准确描述，以及对实体中各个字段的准确描述，体会 @ApiModel 注解与 @ApiModelProperty 注解作用效果的不同之处。

实现思路：

第一步：使用 @ApiModel 注解对实体类进行描述。

第二步：使用 @ApiModelProperty 注解对实体类中的所有字段参数进行描述。

第三步：查看配置结果，体会两个注解作用效果的不同之处。

实现代码：

实体类：

@ApiModel(value = "用户实体，存储用户相关字段")public class User {    // do something...}

代码解释：

第 1 行，我们在用户实体类的上方使用 @ApiModel 注解的 value 属性对实体类进行描述：用户实体，存储用户相关字段。

实体类中的字段：

@ApiModelProperty(name = "id", value = "用户Id", required = true)private Integer id;@ApiModelProperty(name = "username", value = "用户名", required = true)private String username;@ApiModelProperty(name = "idCard", value = "用户身份证号", required = true)private String idCard;@ApiModelProperty(name = "phone", value = "用户手机号码", required = true)private String phone;

代码解释：

第 1、3、5、7 行，我们使用 @ApiModelProperty 注解的 name 属性、value 属性、required 属性分别定义了字段的名称，内容以及是否必传。

显示结果：

可以看到，在用蓝色框框起来的位置就是我们使用 @ApiModel 对用户实体类所描述的信息，红色框框起来的位置就是使用 @ApiModelProperty 注解对用户实体类中所有的字段所描述的信息。

值得注意的是，在描述字段时，allowEmptyValue 这个属性我们并没有显式的拿来使用，但是 Swagger 还是给我都显示出来了，这是因为 Swagger 默认会将所有字段的 allowEmptyValue 属性置位 false ，表示字段的值可以为空。

Tips ： 一定要注意上述两个注解所作用的效果，@ApiModel 是直接作用在实体类上的，@ApiModelProperty 是直接作用在实体类中所有参数上的，两者不要搞混。

5. @ApiImplicitParams 注解与 @ApiResponses 注解组合实战

实操目标： 以用户登录接口方法为例，实现对该方法中的参数添加描述信息的同时，对接口的返回状态码进行自定义描述。

实现思路：

第一步：使用 @ApiImplicitParams 注解对接口方法中的参数进行描述。

第二步：使用 @ApiResponses 注解对用户登录接口所返回的状态码添加自定义描述信息。

第三步：查看配置结果。

实现代码：

接口中的参数：

@ApiImplicitParams(value = { @ApiImplicitParam(name = "session", value = "用户session数据"),@ApiImplicitParam(name = "user", value = "用户登录对象参数") })public ServerResponse<User> login(HttpSession session, User user){    // do something...}

代码解释：

这段代码我们在前面已经介绍过了，显示效果请参考上述截图，这里不再赘述。

自定义接口返回状态码：

@ApiResponses(value = {   @ApiResponse(code = 601, message = "请求成功",  @ApiResponse(code = 602, message = "请求失败"),  @ApiResponse(code = 603, message = "参数传递非")})public ServerResponse<User> login(HttpSession session, User user){    // do something...}

代码解释：

1-3 行，我们使用 @ApiResponses 注解对用户登录接口的返回状态码添加了多条自定义描述信息。

显示结果：

可以看到，601、602、603 及其右侧所对应的文字描述就是我们使用 @ApiResponses 注解所描述的信息了。

Tips ：

1. 在实际项目开发中，如果有需要对一个接口的返回状态码添加描述信息，则请在对接口中参数进行描述时一并添加，@ApiImplicitParams 注解和 @ApiResponses 注解经常一起使用。

2. @ApiResponses 注解的使用方法同学们一定要注意，他只有一个属性 value ，并没有其它额外的属性，在使用时一定要注意 value 属性所指定的方式。

6. 小结

本小节针对在 Swagger 中经常在项目开发中使用的几个注解做了进一步介绍，针对 Swagger 中不同注解搭配使用以及多注解组合使用的情况采用图文并茂的方式做了详细介绍和应用剖析，旨在帮助同学们在了解各个注解及其属性之后真正的可以将所学应用到真实的实际项目开发中。

因为本小节偏于实战，注重实操，所以各位同学在学习本小节时应该将本节中所涉及的代码跟着手动敲一遍，然后结合自己的项目或者自己创建的 Demo 来进行学习，这是掌握本节内容最快最直接的方式，也是为将来在项目中使用 Swagger 打下一定的基础。

本小节为 "Swagger 注解" 这一章节中的最后一篇文章，在本章中分别对 Swagger 中的注解做了详细介绍和应用剖析，针对在实际项目中使用频率很高的注解做了进一步的组合实操讲解，掌握本章节内容是学好 Swagger 的基础，所以请同学们在充分掌握本章内容之后再继续学习下面的内容。