Swagger - 注解組合實(shí)戰(zhàn)

1. 前言

寫(xiě)到這里呢，在 Swagger 中的注解及其屬性都給大家介紹完畢了，那么我們現(xiàn)在需要掌握的就是在真正的項(xiàng)目中對(duì)這些注解進(jìn)行實(shí)操，達(dá)到真正會(huì)使用的目的。

在前面所講課程中，課程內(nèi)容都是針對(duì) Swagger 中的一個(gè)注解進(jìn)行介紹，并不會(huì)介紹各個(gè)注解間都有一個(gè)什么樣的關(guān)系，以及各個(gè)主鍵間如何搭配或者配合使用。

針對(duì)上述問(wèn)題，本節(jié)會(huì)結(jié)合幾個(gè)在 Swagger 中使用頻率非常高的注解進(jìn)行組合式講解，無(wú)論是兩個(gè)注解間的搭配使用，還是多個(gè)注解間的配合使用，我都會(huì)在本節(jié)中進(jìn)行詳細(xì)介紹，小伙伴們趕快打擊精神來(lái)學(xué)習(xí)吧！

本節(jié)會(huì)結(jié)合以下幾個(gè)常用注解進(jìn)行組合實(shí)戰(zhàn)講解：

• @Api 注解；
• @ApiOperation 注解；
• @ApiParam 注解；
• @ApiImplicitParams 注解；
• @ApiResponses 注解；
• @ApiModel 注解；
• @ApiModelProperty 注解。

本節(jié)主要內(nèi)容有：

• @Api 注解與 @ApiOperation 注解組合實(shí)戰(zhàn)；
• @ApiParam 注解與 @ApiImplicitParams 注解組合實(shí)戰(zhàn)；
• @ApiModel 注解與 @ApiModelProperty 注解組合實(shí)戰(zhàn)；
• @ApiImplicitParams 注解與 @ApiResponses 注解組合實(shí)戰(zhàn)。

希望大家在學(xué)習(xí)本節(jié)過(guò)程中能夠真正掌握多個(gè)注解間配合使用的方法，做到融會(huì)貫通，隨手拈來(lái)。

2. @Api 注解與 @ApiOperation 注解組合實(shí)戰(zhàn)

實(shí)操目標(biāo)： 實(shí)現(xiàn)接口類(lèi)與接口類(lèi)中所有接口方法的準(zhǔn)確描述。

實(shí)現(xiàn)思路：

第一步：使用 @Api 注解對(duì)接口類(lèi)進(jìn)行描述。

第二步：使用 @ApiOperation 注解對(duì)接口類(lèi)中所有接口方法進(jìn)行描述。

第三步：查看配置結(jié)果。

實(shí)現(xiàn)代碼：

接口類(lèi)：

@Api(value = "user-controller", description = "用戶(hù)業(yè)務(wù)相關(guān)接口類(lèi)", tags = {"user"})
public class UserController{
    // do something...
}

代碼解釋?zhuān)?/strong>

第 1 行，我們?cè)诮涌陬?lèi)的上方使用 @Api 注解的 value 屬性和 description 屬性以及 tags 屬性為接口類(lèi)添加了一些文字描述信息來(lái)對(duì)接口類(lèi)進(jìn)行一些必要的描述。

其中，value 屬性表示接口類(lèi)在 Swagger 界面上所顯示的名稱(chēng)，description 表示對(duì)接口類(lèi)的描述，tags 屬性則表示對(duì)該接口類(lèi)添加一個(gè)分組，表明該接口類(lèi)是屬于哪一組的。

實(shí)現(xiàn)代碼：

接口方法：

@ApiOperation(name = "user", value = "用戶(hù)登錄對(duì)象", tags = {"user"})
public ServerResponse<User> login(HttpSession session, User user){
    // do something...
}

代碼解釋?zhuān)?/strong>

第 1 行，我們?cè)诮涌诜椒ㄉ鲜褂?@ApiOperation 注解的 name 和 value 屬性來(lái)對(duì)接口方法中的參數(shù)進(jìn)行說(shuō)明，使用 tags 屬性來(lái)對(duì)該接口方法進(jìn)行一個(gè)分組。

顯示結(jié)果：

可以看到，在第一個(gè)標(biāo)簽的位置，從左到右分別表示對(duì)該用戶(hù)相關(guān)接口類(lèi)的分組名稱(chēng) user ， 以及對(duì)該用戶(hù)接口類(lèi)的說(shuō)明：‘用戶(hù)相關(guān)接口類(lèi)’。

在第二個(gè)標(biāo)簽位置，表示對(duì)用戶(hù)登錄接口方法中的 user 對(duì)象類(lèi)型的參數(shù)的說(shuō)明：‘用戶(hù)登錄對(duì)象’。

Tips ：

1. 如果在一個(gè)接口類(lèi)中，我們使用了 @Api 注解的 tags 屬性來(lái)對(duì)該接口分組，那么該接口類(lèi)中的所有接口都將默認(rèn)被分到該類(lèi)中，除非我們使用 @ApiOperation 注解的 tags 屬性為接口方法重新指定了另外一個(gè)分組。
2. 在實(shí)際項(xiàng)目開(kāi)發(fā)中，@ApiOperation 注解與 @Api 注解經(jīng)常這樣搭配起來(lái)用，可以說(shuō)，只要使用 Swagger 那么必定會(huì)這么用，這種使用方法同學(xué)們必須掌握。
3. 不同版本的 Swagger 顯示可能會(huì)有不同，這點(diǎn)請(qǐng)同學(xué)們注意。

3. @ApiParam 注解與 @ApiImplicitParams 注解組合實(shí)戰(zhàn)

實(shí)操目標(biāo)： 實(shí)現(xiàn)對(duì)接口方法中多個(gè)參數(shù)的準(zhǔn)確描述，同時(shí)體會(huì) @ApiParam 注解與 @ApiImplicitParams 注解使用時(shí)的差異。

實(shí)現(xiàn)思路：

第一步：使用 @ApiParam 注解對(duì)接口方法中的一個(gè)參數(shù)進(jìn)行描述，并查看其描述結(jié)果。

第二步：使用 @ApiImplicitParams 注解對(duì)接口方法中的多個(gè)參數(shù)進(jìn)行描述，并查看其描述結(jié)果。

第三步：總結(jié)對(duì)比兩個(gè)注解使用時(shí)的差異。

實(shí)現(xiàn)代碼：

@ApiParam 注解作用在接口方法上時(shí)：

@ApiParam(name = "session", value = "用戶(hù)session數(shù)據(jù)")
public ServerResponse<User> login(HttpSession session, User user){
    // do something...
}

顯示結(jié)果：

可以看到，在紅色框框起來(lái)的位置并沒(méi)有看到關(guān)于 session 參數(shù)的說(shuō)明 (正常的話(huà)會(huì)在紅框中出現(xiàn)對(duì) session 參數(shù)的說(shuō)明)。

• @ApiImplicitParams 注解作用在接口方法上時(shí)

@ApiImplicitParams(value = { @ApiImplicitParam(name = "session", value = "用戶(hù)session數(shù)據(jù)"),
@ApiImplicitParam(name = "user", value = "用戶(hù)登錄對(duì)象參數(shù)") })
public ServerResponse<User> login(HttpSession session, User user){
    // do something...
}

顯示結(jié)果：

可以看到，在用紅色框框起來(lái)的位置分別顯示出了使用 @ApiImplicitParams 注解對(duì)參數(shù)所描述的信息，并且是多個(gè)參數(shù)。

Tips ：

1. 如果你使用的是 Swagger 的低版本且只需要對(duì)接口中的一個(gè)參數(shù)進(jìn)行描述，則可以使用 @ApiParam 注解；如果你使用的是 Swagger 高版本且需要對(duì)多個(gè)接口中的參數(shù)進(jìn)行描述，則應(yīng)該首先考慮使用 @ApiImplicitParams 注解。
2. 在實(shí)際項(xiàng)目開(kāi)發(fā)中，如果需要對(duì)接口中的參數(shù)進(jìn)行描述，那么無(wú)論需要描述幾個(gè)參數(shù)，都應(yīng)該首先考慮使用 @ApiImplicitParams 注解，因?yàn)樗募嫒菪允亲詈玫摹?/li>
3. 在 Swagger 高版本中，@ApiParam 注解并不會(huì)有任何效果，而 @ApiImplicitParams 注解則替代了 @ApiParam 注解的作用效果，并且支持對(duì)多個(gè)參數(shù)同時(shí)進(jìn)行描述，這點(diǎn)需要同學(xué)們注意。

4. @ApiModel 注解與 @ApiModelProperty 注解組合實(shí)戰(zhàn)

實(shí)操目標(biāo)： 以用戶(hù)實(shí)體類(lèi)為例，實(shí)現(xiàn)對(duì)用戶(hù)業(yè)務(wù)實(shí)體 (Entity) 的準(zhǔn)確描述，以及對(duì)實(shí)體中各個(gè)字段的準(zhǔn)確描述，體會(huì) @ApiModel 注解與 @ApiModelProperty 注解作用效果的不同之處。

實(shí)現(xiàn)思路：

第一步：使用 @ApiModel 注解對(duì)實(shí)體類(lèi)進(jìn)行描述。

第二步：使用 @ApiModelProperty 注解對(duì)實(shí)體類(lèi)中的所有字段參數(shù)進(jìn)行描述。

第三步：查看配置結(jié)果，體會(huì)兩個(gè)注解作用效果的不同之處。

實(shí)現(xiàn)代碼：

實(shí)體類(lèi)：

@ApiModel(value = "用戶(hù)實(shí)體，存儲(chǔ)用戶(hù)相關(guān)字段")
public class User {
    // do something...
}

代碼解釋?zhuān)?/strong>

第 1 行，我們?cè)谟脩?hù)實(shí)體類(lèi)的上方使用 @ApiModel 注解的 value 屬性對(duì)實(shí)體類(lèi)進(jìn)行描述：用戶(hù)實(shí)體，存儲(chǔ)用戶(hù)相關(guān)字段。

實(shí)體類(lèi)中的字段：

@ApiModelProperty(name = "id", value = "用戶(hù)Id", required = true)
private Integer id;
@ApiModelProperty(name = "username", value = "用戶(hù)名", required = true)
private String username;
@ApiModelProperty(name = "idCard", value = "用戶(hù)身份證號(hào)", required = true)
private String idCard;
@ApiModelProperty(name = "phone", value = "用戶(hù)手機(jī)號(hào)碼", required = true)
private String phone;

代碼解釋?zhuān)?/strong>

第 1、3、5、7 行，我們使用 @ApiModelProperty 注解的 name 屬性、value 屬性、required 屬性分別定義了字段的名稱(chēng)，內(nèi)容以及是否必傳。

顯示結(jié)果：

可以看到，在用藍(lán)色框框起來(lái)的位置就是我們使用 @ApiModel 對(duì)用戶(hù)實(shí)體類(lèi)所描述的信息，紅色框框起來(lái)的位置就是使用 @ApiModelProperty 注解對(duì)用戶(hù)實(shí)體類(lèi)中所有的字段所描述的信息。

值得注意的是，在描述字段時(shí)，allowEmptyValue 這個(gè)屬性我們并沒(méi)有顯式的拿來(lái)使用，但是 Swagger 還是給我都顯示出來(lái)了，這是因?yàn)?Swagger 默認(rèn)會(huì)將所有字段的 allowEmptyValue 屬性置位 false ，表示字段的值可以為空。

Tips ： 一定要注意上述兩個(gè)注解所作用的效果，@ApiModel 是直接作用在實(shí)體類(lèi)上的，@ApiModelProperty 是直接作用在實(shí)體類(lèi)中所有參數(shù)上的，兩者不要搞混。

5. @ApiImplicitParams 注解與 @ApiResponses 注解組合實(shí)戰(zhàn)

實(shí)操目標(biāo)： 以用戶(hù)登錄接口方法為例，實(shí)現(xiàn)對(duì)該方法中的參數(shù)添加描述信息的同時(shí)，對(duì)接口的返回狀態(tài)碼進(jìn)行自定義描述。

實(shí)現(xiàn)思路：

第一步：使用 @ApiImplicitParams 注解對(duì)接口方法中的參數(shù)進(jìn)行描述。

第二步：使用 @ApiResponses 注解對(duì)用戶(hù)登錄接口所返回的狀態(tài)碼添加自定義描述信息。

第三步：查看配置結(jié)果。

實(shí)現(xiàn)代碼：

接口中的參數(shù)：

@ApiImplicitParams(value = { @ApiImplicitParam(name = "session", value = "用戶(hù)session數(shù)據(jù)"),
@ApiImplicitParam(name = "user", value = "用戶(hù)登錄對(duì)象參數(shù)") })
public ServerResponse<User> login(HttpSession session, User user){
    // do something...
}

代碼解釋?zhuān)?/strong>

這段代碼我們?cè)谇懊嬉呀?jīng)介紹過(guò)了，顯示效果請(qǐng)參考上述截圖，這里不再贅述。

自定義接口返回狀態(tài)碼：

@ApiResponses(value = { 
  @ApiResponse(code = 601, message = "請(qǐng)求成功",
  @ApiResponse(code = 602, message = "請(qǐng)求失敗"),
  @ApiResponse(code = 603, message = "參數(shù)傳遞非")})
public ServerResponse<User> login(HttpSession session, User user){
    // do something...
}

代碼解釋?zhuān)?/strong>

1-3 行，我們使用 @ApiResponses 注解對(duì)用戶(hù)登錄接口的返回狀態(tài)碼添加了多條自定義描述信息。

顯示結(jié)果：

可以看到，601、602、603 及其右側(cè)所對(duì)應(yīng)的文字描述就是我們使用 @ApiResponses 注解所描述的信息了。

Tips ：

1. 在實(shí)際項(xiàng)目開(kāi)發(fā)中，如果有需要對(duì)一個(gè)接口的返回狀態(tài)碼添加描述信息，則請(qǐng)?jiān)趯?duì)接口中參數(shù)進(jìn)行描述時(shí)一并添加，@ApiImplicitParams 注解和 @ApiResponses 注解經(jīng)常一起使用。
2. @ApiResponses 注解的使用方法同學(xué)們一定要注意，他只有一個(gè)屬性 value ，并沒(méi)有其它額外的屬性，在使用時(shí)一定要注意 value 屬性所指定的方式。

6. 小結(jié)

本小節(jié)針對(duì)在 Swagger 中經(jīng)常在項(xiàng)目開(kāi)發(fā)中使用的幾個(gè)注解做了進(jìn)一步介紹，針對(duì) Swagger 中不同注解搭配使用以及多注解組合使用的情況采用圖文并茂的方式做了詳細(xì)介紹和應(yīng)用剖析，旨在幫助同學(xué)們?cè)诹私飧鱾€(gè)注解及其屬性之后真正的可以將所學(xué)應(yīng)用到真實(shí)的實(shí)際項(xiàng)目開(kāi)發(fā)中。

因?yàn)楸拘」?jié)偏于實(shí)戰(zhàn)，注重實(shí)操，所以各位同學(xué)在學(xué)習(xí)本小節(jié)時(shí)應(yīng)該將本節(jié)中所涉及的代碼跟著手動(dòng)敲一遍，然后結(jié)合自己的項(xiàng)目或者自己創(chuàng)建的 Demo 來(lái)進(jìn)行學(xué)習(xí)，這是掌握本節(jié)內(nèi)容最快最直接的方式，也是為將來(lái)在項(xiàng)目中使用 Swagger 打下一定的基礎(chǔ)。

本小節(jié)為 "Swagger 注解" 這一章節(jié)中的最后一篇文章，在本章中分別對(duì) Swagger 中的注解做了詳細(xì)介紹和應(yīng)用剖析，針對(duì)在實(shí)際項(xiàng)目中使用頻率很高的注解做了進(jìn)一步的組合實(shí)操講解，掌握本章節(jié)內(nèi)容是學(xué)好 Swagger 的基礎(chǔ)，所以請(qǐng)同學(xué)們?cè)诔浞终莆毡菊聝?nèi)容之后再繼續(xù)學(xué)習(xí)下面的內(nèi)容。