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 注解及其常用屬性時，各位同學注意注意區分這三個注解的不同之處，理清在不同場景下應該如何應用這三個注解的關系就可以了。