Swagger-Info、Contact、License 注解

1. 前言

本節(jié)會結(jié)合一個用戶相關(guān)接口類來為大家介紹 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 界面上的一些信息進(jìn)行描述，一般都不會單獨使用，經(jīng)常和 @SwaggerDifinitiion 注解搭配使用，他們的不同點在于：

Info 注解是對 swagger-ui 界面上的基本信息進(jìn)行描述，包括但不限于界面的標(biāo)題、界面的介紹等。

Contact 注解是對 swagger-ui 界面上的一些和接口有關(guān)的聯(lián)系人的信息進(jìn)行描述，包括但不限于開發(fā)人員名稱、地址等。

License 注解是對 swagger-ui 界面上的一些和接口有關(guān)的服務(wù)條款或者使用的開源協(xié)議進(jìn)行描述，包括服務(wù)名稱、服務(wù)所在地址。

下面我們來看一下上述三個注解中都包括哪些常用屬性。

3. 注解主要屬性匯總

Info 注解

Contact 注解

License 注解

4. 屬性詳解

4.1 Info 注解相關(guān)屬性

title() 、version() 、 description() 屬性

定義：

title() 屬性就是對界面的標(biāo)題做一個描述，即描述界面的標(biāo)題叫什么。

version() 屬性就是對界面的版本做一個描述，通常這個版本指的是接口文檔的版本，即描述當(dāng)前接口文檔屬于什么版本。

description() 屬性就是對界面做一個簡單扼要的介紹，即用來描述界面是用來干什么的或者一些其他的注意事項等。

使用方法：

上述三個屬性均可以在 Info 注解中注解聲明，具體使用方法請看如下代碼：(現(xiàn)在你不需要理解業(yè)務(wù)代碼代表什么意思，重點看所使用的注解及屬性即可，下同）。

@SwaggerDefinition(info = @Info(title = "慕課網(wǎng) Wiki 教程", version = "1.0", description = "此界面為慕課網(wǎng) Wiki-Swagger 教程界面"))
public class UserController {
    // do something...
} 

代碼解釋：

1-3 行，我們在用戶相關(guān)接口類的上方定義了 Info 注解的 title 、 version 、 description 屬性，由于篇幅有限，這里就不截圖演示了。

Tips ： Info 注解的使用方法我們可以看到是搭配 @SwaggerDefinition 注解的，在實際項目開發(fā)中，Info 注解很少使用，所以大家只要了解基本定義和基本用法即可。

4.2 Contact 注解相關(guān)屬性

name() 、url() 、email() 屬性

定義：

name 屬性就是用來描述開發(fā)或者配置這個界面的開發(fā)者或者管理員的名稱，一般是指系統(tǒng)開發(fā)人員的名稱。

url 屬性就是對通過 name 屬性所描述的人的進(jìn)一步介紹信息，如果這個人有個人博客或者其他網(wǎng)站介紹的話，都可以通過該屬性進(jìn)行指名。

email 屬性就是描述 name 屬性所描述的人的郵箱地址，即這個人的郵箱地址是什么。

使用方法：

name 、 url 、 email 屬性都可以直接在 Contact 注解中直接聲明來使用，具體使用方法請看下述代碼：

@SwaggerDefinition(info = @Info(title = "慕課網(wǎng) Wiki 教程", version = "1.0", description = "此界面為慕課網(wǎng) Wiki-Swagger 教程界面",
contact = @Contact(name = "Steafan_" , url = "暫無", email = "保密")))
public class UserController {
    // do something...
} 

代碼解釋：

1-3 行，我們在 SwaggerDefinition 注解的 info 屬性中使用了 contact 屬性，并將其值描述為 @Contact 注解的相關(guān)屬性，這就是 @Contact 注解及其屬性的使用方法，由于篇幅有限，這里就不截圖演示了。

Tips ：

1. 在實際項目開發(fā)功能中，name 屬性的值可以是任意名稱，只要在有問題時可以查詢到這個人是誰就可以了。
2. email 屬性的值一般都是具體人的真實郵箱了，因為很多公司是通過郵件的方式來進(jìn)行問題的溝通。
3. url 屬性的值一般指的就是具體人的個人技術(shù)博客，或者自建的個人網(wǎng)站等，通過這種方式可以全方面了解這個人的技術(shù)水平。

4.3 License 注解相關(guān)屬性

name() 、url() 屬性

定義：

name 屬性就是用來描述界面上，具體來講是系統(tǒng)中所使用的服務(wù)條款、開源協(xié)議等。

url 屬性就是用來描述其服務(wù)條款或開源協(xié)議所引用的地址信息。

使用方法：

name 、 url 屬性都可以直接在 License 注解中直接聲明來使用，具體使用方法請看下述代碼：

@SwaggerDefinition(info = @Info(title = "慕課網(wǎng) Wiki 教程", version = "1.0", description = "此界面為慕課網(wǎng) Wiki-Swagger 教程界面",
contact = @Contact(name = "Steafan_" , url = "暫無", email = "保密"),
license = @License(name = "慕課網(wǎng) Wiki 教程服務(wù)條款", url = "還在建設(shè)中，敬請期待")))
public class UserController {
    // do something...
} 

代碼解釋：

2-4 行，我們在 SwaggerDefinition 注解的 info 屬性中，使用了 license 屬性，并將其值描述為 @License 注解的相關(guān)屬性，這就是 @License 注解及其屬性的使用方法，由于篇幅有限，這里就不截圖演示了。

Tips ： 只要項目中存在引用了外部服務(wù)條款或者開源協(xié)議的情況，無論使用規(guī)模多少，都應(yīng)該用 @License 注解的相關(guān)屬性表明，以免由于版權(quán)問題引起不必要的糾紛。

5. 小結(jié)

本小節(jié)對 Swagger 中的 Info、Contact、License 三個小注解及其注解中的常用屬性做了詳細(xì)介紹，針對注解中經(jīng)常在實際項目開發(fā)中使用的屬性進(jìn)行了重點介紹和應(yīng)用剖析。

Info、Contact、License 這三個注解其實并沒有太大的作用，因為這三個注解在項目中所起的作用通過一個 Swagger 配置類即可完成，而且配置類在配置起來還相對靈活，所以我建議：如果項目中需要配置 swagger-ui 界面的描述信息，請綜合考慮之后再決定是采用配置類的形式還是采用注解的形式。

在學(xué)習(xí) Info、Contact、License 注解及其常用屬性時，各位同學(xué)注意注意區(qū)分這三個注解的不同之處，理清在不同場景下應(yīng)該如何應(yīng)用這三個注解的關(guān)系就可以了。