Swagger-Info、Contact、License 注解

1. 前言

本節(jié)會(huì)結(jié)合一個(gè)用戶相關(guān)接口類來(lái)為大家介紹 Swagger 中的三個(gè)小注解 - Info、Contact、License 注解及所提供的常用屬性。

Info、Contact、License 這三個(gè)注解均不能單獨(dú)使用，都需要搭配其他注解才能使用，鑒于篇幅有限，所以這里就不再對(duì)搭配使用的注解逐一介紹了。

對(duì)于這三個(gè)小注解，我們只需要了解他們分別代表什么含義，以及他們都有哪些屬性，屬性的作用都是什么就可以了。

重點(diǎn)講解的屬性：

• Info 注解的 title 、 version 、 description ；

• Contact 注解的 name 、 url 、 email ；

• License 注解的 name 、 url。

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

Info 、Contact 、License、三個(gè)注解都是作用在接口類上的注解，用來(lái)對(duì) swagge-ui 界面上的一些信息進(jìn)行描述，一般都不會(huì)單獨(dú)使用，經(jīng)常和 @SwaggerDifinitiion 注解搭配使用，他們的不同點(diǎn)在于：

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

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

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

下面我們來(lái)看一下上述三個(gè)注解中都包括哪些常用屬性。

3. 注解主要屬性匯總

Info 注解

Contact 注解

License 注解

4. 屬性詳解

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

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

定義：

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

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

description() 屬性就是對(duì)界面做一個(gè)簡(jiǎn)單扼要的介紹，即用來(lái)描述界面是用來(lái)干什么的或者一些其他的注意事項(xiàng)等。

使用方法：

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

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

代碼解釋：

1-3 行，我們?cè)谟脩粝嚓P(guān)接口類的上方定義了 Info 注解的 title 、 version 、 description 屬性，由于篇幅有限，這里就不截圖演示了。

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

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

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

定義：

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

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

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

使用方法：

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

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

代碼解釋：

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

Tips ：

1. 在實(shí)際項(xiàng)目開(kāi)發(fā)功能中，name 屬性的值可以是任意名稱，只要在有問(wèn)題時(shí)可以查詢到這個(gè)人是誰(shuí)就可以了。
2. email 屬性的值一般都是具體人的真實(shí)郵箱了，因?yàn)楹芏喙臼峭ㄟ^(guò)郵件的方式來(lái)進(jìn)行問(wèn)題的溝通。
3. url 屬性的值一般指的就是具體人的個(gè)人技術(shù)博客，或者自建的個(gè)人網(wǎng)站等，通過(guò)這種方式可以全方面了解這個(gè)人的技術(shù)水平。

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

name() 、url() 屬性

定義：

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

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

使用方法：

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

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

代碼解釋：

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

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

5. 小結(jié)

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

Info、Contact、License 這三個(gè)注解其實(shí)并沒(méi)有太大的作用，因?yàn)檫@三個(gè)注解在項(xiàng)目中所起的作用通過(guò)一個(gè) Swagger 配置類即可完成，而且配置類在配置起來(lái)還相對(duì)靈活，所以我建議：如果項(xiàng)目中需要配置 swagger-ui 界面的描述信息，請(qǐng)綜合考慮之后再?zèng)Q定是采用配置類的形式還是采用注解的形式。

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