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

Contact 注解

License 注解

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 注解及其常用属性时，各位同学注意注意区分这三个注解的不同之处，理清在不同场景下应该如何应用这三个注解的关系就可以了。