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

1. 前言

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

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

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

本節(jié)會結(jié)合以下幾個常用注解進(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é)過程中能夠真正掌握多個注解間配合使用的方法，做到融會貫通，隨手拈來。

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

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

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

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

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

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

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

接口類：

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

代碼解釋：

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

其中，value 屬性表示接口類在 Swagger 界面上所顯示的名稱，description 表示對接口類的描述，tags 屬性則表示對該接口類添加一個分組，表明該接口類是屬于哪一組的。

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

接口方法：

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

代碼解釋：

第 1 行，我們在接口方法上使用 @ApiOperation 注解的 name 和 value 屬性來對接口方法中的參數(shù)進(jìn)行說明，使用 tags 屬性來對該接口方法進(jìn)行一個分組。

顯示結(jié)果：

可以看到，在第一個標(biāo)簽的位置，從左到右分別表示對該用戶相關(guān)接口類的分組名稱 user ， 以及對該用戶接口類的說明：‘用戶相關(guān)接口類’。

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

Tips ：

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

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

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

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

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

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

第三步：總結(jié)對比兩個注解使用時的差異。

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

@ApiParam 注解作用在接口方法上時：

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

顯示結(jié)果：

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

• @ApiImplicitParams 注解作用在接口方法上時

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

顯示結(jié)果：

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

Tips ：

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

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

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

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

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

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

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

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

實(shí)體類：

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

代碼解釋：

第 1 行，我們在用戶實(shí)體類的上方使用 @ApiModel 注解的 value 屬性對實(shí)體類進(jìn)行描述：用戶實(shí)體，存儲用戶相關(guān)字段。

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

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

代碼解釋：

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

顯示結(jié)果：

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

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

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

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

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

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

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

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

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

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

接口中的參數(shù)：

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

代碼解釋：

這段代碼我們在前面已經(jīng)介紹過了，顯示效果請參考上述截圖，這里不再贅述。

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

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

代碼解釋：

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

顯示結(jié)果：

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

Tips ：

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

6. 小結(jié)

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

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

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