Swagger-ApiOperation 注解

1. 前言

本節(jié)會結(jié)合一個用戶登錄接口給大家介紹 Swagger 中核心注解之一 ApiOperation 及所提供的常用屬性。

ApiOperation 注解在 Swagger 中扮演著非常重要的角色，基本上只要使用 Swagger 那就必須要用 ApiOperation 注解。

重點(diǎn)講解的屬性：value 、tags 、notes ;
概要講解的屬性：httpMethod、nickname、protocols、hidden、code。

希望大家在學(xué)習(xí)本節(jié)過程中能夠分清主次，有的放矢。

2. 什么是 ApiOperation 注解？

在我們?nèi)粘９ぷ髦?，后端小伙伴們?jīng)常會寫一些接口，為了方便讓大家知道這些接口的功能作用，我們就需要給接口添加一些具體的描述信息，為此，在 Swagger 中，我們就需要使用 ApiOperation 注解來描述我們寫的接口。

ApiOperation 注解提供了豐富的屬性來允許我們自定義接口描述信息，包括接口名稱，接口所屬分組等。

下面我們來看一下 ApiOperation 注解中都包括哪些主要屬性。（注意：我們只介紹還在使用的屬性，那些被 Swagger 官方已經(jīng)廢棄的屬性不再介紹）。

3. ApiOperation 注解主要屬性匯總

4. 屬性詳解

4.1 value () 屬性

定義：

該屬性就是描述接口的作用是什么，即接口是用來干什么的。

使用方法：

在 ApiOperatio 注解中聲明 value 的值即可。例如，就用戶登錄接口而言，只需要將 value 的值寫為 ‘用戶登錄’就好了，這樣我們就能很清楚的知道這個接口就是來做用戶登錄用的，如下代碼段所示（現(xiàn)在你不需要理解業(yè)務(wù)代碼代表什么意思，重點(diǎn)看方法上使用的注解及屬性即可，下同）。

@ApiOperation(value = "用戶登錄")
public CommonResponse<User> userLogin(HttpSession session, @RequestBody User user){
    return userService.login(session, user);
}

代碼解釋：

第 1 行，我們在 userLogin 方法的上方使用了 @ApiOperation 的 value 屬性來描述接口的作用。

顯示結(jié)果：

在結(jié)果顯示界面的右上角就是我們使用 value 屬性描述的信息（用戶登錄）。

Tips ： 項(xiàng)目中的接口文檔可能需要看的人很多，不只是開發(fā)人員看，客戶有時候也要看，所以 value 屬性值的描述，應(yīng)該本著通俗易懂的原則進(jìn)行，一定要根據(jù)接口方法實(shí)現(xiàn)的具體業(yè)務(wù)內(nèi)容來描述，不能隨便描述，不能使用表意不清楚的詞語來描述，更不能使用專業(yè)術(shù)語來描述。

4.2 tags () 屬性

定義：

該屬性就是對實(shí)現(xiàn)相同業(yè)務(wù)場景的接口做一個分組。

使用方法：

在 ApiOperatio 注解中聲明 tags 的值即可，如果沒有描述則默認(rèn)值為空。例如，就用戶登錄接口而言，該接口屬于用戶業(yè)務(wù)分組中，所以我們將 tags 的值描述為‘用戶’或者‘user’，這樣我們就能很清楚的看到這個接口是屬于用戶業(yè)務(wù)組的，如下代碼段所示。

@ApiOperation(tags = {"user"})
public CommonResponse<User> userLogin(HttpSession session, @RequestBody User user){
    return userService.login(session, user);
}

代碼解釋：

第 1 行，我們在 userLogin 方法的上方使用了 @ApiOperation 注解的 tags 屬性來描述接口所屬的業(yè)務(wù)分組。

顯示結(jié)果：

我們可以看到在頂部有一個 user 字樣，這個就是我們規(guī)定的分組名稱，也就是 tags 里寫的 user 了。

Tips：

1. 在實(shí)際項(xiàng)目開發(fā)工作中，往往一個接口可能涉及多個業(yè)務(wù)，這種情況需要我們對接口進(jìn)行多個分組，而 tags 屬性的類型是字符串類型的數(shù)組，可以描述一個或多個值，如存在多值時，應(yīng)該使用如下方法來描述。
2. tags 屬性值的描述規(guī)則同上述 value 屬性。

@ApiOperation(tags = {"user", "customer"})

4.3 notes () 屬性

定義：

該屬性就是對接口方法做進(jìn)一步詳細(xì)的描述。

使用方法：

在 ApiOperatio 注解中聲明 notes 的值即可，如果沒有描述則默認(rèn)值為空。例如，如果我想添加對用戶登錄接口的詳細(xì)描述信息，那么我可以這樣寫 notes = “用戶登錄接口必須是 post 請求”，這種使用效果會直接顯示在接口面板中，當(dāng)做接口的主要內(nèi)容進(jìn)行顯示，如下代碼段所示。

@ApiOperation(notes = {"用戶登錄接口必須是post請求"})
public CommonResponse<User> userLogin(HttpSession session, @RequestBody User user){
    return userService.login(session, user);
}

代碼解釋：

第 1 行，我們在 userLogin 方法的上方使用了 @ApiOperation 注解的 notes 屬性來進(jìn)一步描述接口的詳細(xì)信息。

顯示結(jié)果：

在我用紅框圈起來的地方我們可以看到 Implementation Notes 下放就是我們對該接口的進(jìn)一步詳細(xì)描述，其顯示在了接口的主要內(nèi)容區(qū)域里面。

Tips ：

1. notes 屬性一般用來描述接口的一些必要詳細(xì)信息，如果是一般的信息則最好不要使用 notes 去描述。
2. 使用 notes 屬性來進(jìn)一步詳細(xì)描述接口這一行為往往在項(xiàng)目開發(fā)中不是必須的。

階段小結(jié)（一）

以上是對 ApiOperation 注解中經(jīng)常使用的三個屬性進(jìn)行的詳細(xì)介紹，value，tags，notes 這三個屬性不管是在項(xiàng)目開發(fā)中，還是在需求溝通中，使用的都很頻繁，所以，真正掌握這三個屬性是用好 Swagger 的重要前提。在學(xué)習(xí)這三個屬性時，大家應(yīng)該自己對比并總結(jié)它們之間的差異，通過不斷的使用來發(fā)現(xiàn)它們的使用規(guī)律，這一點(diǎn)很重要。

在詳細(xì)講解完 ApiOperation 重要屬性之后，下面我將針對在 ApiOperation 注解中，使用頻率不是很高，但是有時也會用到的一些屬性做概要性講解，這些屬性分別是：httpMethod、nickname、protoclos、hidden、code。

4.4 httpMethod () 和 nickname () 屬性

定義：

httpMethod () 屬性就是對接口的請求類型進(jìn)行一個約定，常用的接口類型有：“GET”, “HEAD”, “POST”, “PUT”, “DELETE”, “OPTIONS”。

nickname () 屬性是為接口起一個別名，方便前后端溝通使用。

使用方法：

httpMethod () 屬性默認(rèn)值為空，但是 Swagger 在處理時會默認(rèn)獲取項(xiàng)目所采用的接口請求類型，我們可以不用專門設(shè)置，如果一定要設(shè)置該屬性，則只允許設(shè)置 http 協(xié)議規(guī)定的屬性，不能隨意設(shè)置。

nickname () 屬性允許我們?yōu)榻涌谠O(shè)置一個別名，在設(shè)置別名之后，我們設(shè)置的別名會出現(xiàn)在瀏覽器地址欄中，如下代碼段所示（httpMethod () 屬性自動獲取值，這里不再演示）。

@ApiOperation(nickname = "userLoginNickName")
public CommonResponse<User> userLogin(HttpSession session, @RequestBody User user){
    return userService.login(session, user);
}

代碼解釋：

第 1 行，我們在 userLogin 方法的上方使用了 @ApiOperation 注解的 nickname 屬性來為接口起一個別名。

顯示結(jié)果：

在我用紅框圈起來的地方我們可以看到 userLoginNickName 字樣，這就是我們?yōu)榻涌谒O(shè)置的別名。

Tips ：

1. 不要隨意定義接口的別名，要根據(jù)特定業(yè)務(wù)場景來設(shè)置。
2. 在項(xiàng)目前后端聯(lián)合測試過程中，給接口起一個別名更方便前后端開發(fā)人員的溝通，并沒有其他特殊意義。

4.5 protocols ()、hidden () 和 code () 屬性

定義：

protocols () 屬性就是對接口所使用的網(wǎng)絡(luò)協(xié)議進(jìn)行一個約定，常用的網(wǎng)絡(luò)協(xié)議有：http、https。

hidden () 屬性就是控制接口在 Swagger 界面中的顯隱性。

code () 屬性就是控制接口的返回狀態(tài)，常見的有：200，201，404，500 等。

使用方法：

protocols () 屬性默認(rèn)值為空，但是 Swagger 在處理時會默認(rèn)獲取項(xiàng)目所采用的網(wǎng)絡(luò)協(xié)議，我們可以不用專門設(shè)置，如果一定要設(shè)置該屬性，則只允許設(shè)置 http 協(xié)議規(guī)定的屬性，不能隨意設(shè)置，http, https, ws, wss 這些都是被允許的。

code () 屬性一般不用特定設(shè)置， Swagger 會自動生成接口返回狀態(tài)，這里不再演示。

hidden () 屬性允許我們在 Swagger 生成的接口列表界面上控制接口是否需要顯示，默認(rèn)值為 false，即接口顯示，為 true 時則接口不顯示，如下代碼段所示。

@ApiOperation(hidden = true)
public CommonResponse<User> userLogin(HttpSession session, @RequestBody User user){
    return userService.login(session, user);
}

代碼解釋：

第 1 行，我們在 userLogin 方法的上方使用了 @ApiOperation 注解的 hidden 屬性來隱藏我們的接口。

顯示結(jié)果：

可以看到在接口列表界面，已經(jīng)看不到我們的用戶登錄接口了，這就是當(dāng) hidden 屬性設(shè)置為 true 時所起的作用。

Tips ：

1. 接口的顯隱控制應(yīng)該根據(jù)特定安全策略和特定客戶需求來決定顯隱，不能無故隱藏接口，更不能頻繁的切換接口的顯隱。
2. 在實(shí)際工作中，如果需要隱藏接口則需要和項(xiàng)目組報備情況，說明原因。

階段小結(jié)（二）

以上則是 ApiOperation 注解中的輔助使用屬性的概要介紹，對于剩下的 response、responseContainer、responseReference、produces、consumes 屬性在實(shí)際項(xiàng)目開發(fā)中幾乎很少使用，在這里就不再介紹了，如果大家感興趣可以去 Swagger 的官網(wǎng)查詢相關(guān)資料來了解。

5. 小結(jié)

本小節(jié)對 Swagger 中最經(jīng)常使用的 ApiOperation 注解及其該注解的各個屬性做了詳細(xì)的講解，針對 ApiOperation 注解中經(jīng)常在實(shí)際項(xiàng)目開發(fā)中使用的屬性采用圖文并茂的方式進(jìn)行了重點(diǎn)介紹和應(yīng)用剖析，對于一些在實(shí)際項(xiàng)目開發(fā)中使用基本很少的注解做了概要講解。通過這樣系統(tǒng)的講解，希望大家從注解屬性的定義到具體使用規(guī)范全過程中徹底搞懂 ApiOperation 注解及其注解各屬性的語義規(guī)則、使用場景、注意事項(xiàng)等。