前後端分離swagger接口文檔常見處理

1、swagger2 註解整體說明

用於controller類上：

註解	說明
@Api	對請求類的說明

用於方法上面（說明參數的含義）：

註解	說明
@ApiOperation	方法的說明
@ApiImplicitParams、@ApiImplicitParam	方法的參數的說明；@ApiImplicitParams 用於指定單個參數的說明

用於方法上面（返回參數或對象的說明）：

註解	說明
@ApiResponses、@ApiResponse	方法返回值的說明 ；@ApiResponses 用於指定單個參數的說明

對象類：

註解	說明
@ApiModel	用在JavaBean類上，說明JavaBean的 用途
@ApiModelProperty	用在JavaBean類的屬性上面，說明此屬性的的含議

2、@Api：請求類的說明

@Api：放在 請求的類上，與 @Controller 並列，說明類的作用，如用戶模塊，訂單類等。
	tags="說明該類的作用"
	value="該參數沒什麼意義，所以不需要配置"

• 1
• 2
• 3

示例：

@Api(tags="訂單模塊")
@Controller
public class OrderController {

}

• 1
• 2
• 3
• 4
• 5

@Api 其它屬性配置：

屬性名稱	備註
value	url的路徑值
tags	如果設置這個值、value的值會被覆蓋
description	對api資源的描述
basePath	基本路徑
position	如果配置多個Api 想改變顯示的順序位置
produces	如, “application/json, application/xml”
consumes	如, “application/json, application/xml”
protocols	協議類型，如: http, https, ws, wss.
authorizations	高級特性認證時配置
hidden	配置爲true ，將在文檔中隱藏

3、@ApiOperation：方法的說明

@ApiOperation："用在請求的方法上，說明方法的作用"
	value="說明方法的作用"
	notes="方法的備註說明"

• 1
• 2
• 3

3.1、@ApiImplicitParams、@ApiImplicitParam：方法參數的說明

@ApiImplicitParams：用在請求的方法上，包含一組參數說明
	@ApiImplicitParam：對單個參數的說明	    
	    name：參數名
	    value：參數的漢字說明、解釋
	    required：參數是否必須傳
	    paramType：參數放在哪個地方
	        · header --> 請求參數的獲取：@RequestHeader
	        · query --> 請求參數的獲取：@RequestParam
	        · path（用於restful接口）--> 請求參數的獲取：@PathVariable
	        · body（請求體）-->  @RequestBody User user
	        · form（普通表單提交）	   
	    dataType：參數類型，默認String，其它值dataType="Integer"	   
	    defaultValue：參數的默認值

• 1
• 2
• 3
• 4
• 5
• 6
• 7
• 8
• 9
• 10
• 11
• 12
• 13

示列：

@Api(tags="用戶模塊")
@Controller
public class UserController {
<span class="token annotation punctuation">@ApiOperation</span><span class="token punctuation">(</span>value<span class="token operator">=</span><span class="token string">"用戶登錄"</span><span class="token punctuation">,</span>notes<span class="token operator">=</span><span class="token string">"隨邊說點啥"</span><span class="token punctuation">)</span>
<span class="token annotation punctuation">@ApiImplicitParams</span><span class="token punctuation">(</span><span class="token punctuation">{</span>
	<span class="token annotation punctuation">@ApiImplicitParam</span><span class="token punctuation">(</span>name<span class="token operator">=</span><span class="token string">"mobile"</span><span class="token punctuation">,</span>value<span class="token operator">=</span><span class="token string">"手機號"</span><span class="token punctuation">,</span>required<span class="token operator">=</span><span class="token boolean">true</span><span class="token punctuation">,</span>paramType<span class="token operator">=</span><span class="token string">"form"</span><span class="token punctuation">)</span><span class="token punctuation">,</span>
	<span class="token annotation punctuation">@ApiImplicitParam</span><span class="token punctuation">(</span>name<span class="token operator">=</span><span class="token string">"password"</span><span class="token punctuation">,</span>value<span class="token operator">=</span><span class="token string">"密碼"</span><span class="token punctuation">,</span>required<span class="token operator">=</span><span class="token boolean">true</span><span class="token punctuation">,</span>paramType<span class="token operator">=</span><span class="token string">"form"</span><span class="token punctuation">)</span><span class="token punctuation">,</span>
	<span class="token annotation punctuation">@ApiImplicitParam</span><span class="token punctuation">(</span>name<span class="token operator">=</span><span class="token string">"age"</span><span class="token punctuation">,</span>value<span class="token operator">=</span><span class="token string">"年齡"</span><span class="token punctuation">,</span>required<span class="token operator">=</span><span class="token boolean">true</span><span class="token punctuation">,</span>paramType<span class="token operator">=</span><span class="token string">"form"</span><span class="token punctuation">,</span>dataType<span class="token operator">=</span><span class="token string">"Integer"</span><span class="token punctuation">)</span>
<span class="token punctuation">}</span><span class="token punctuation">)</span>
<span class="token annotation punctuation">@PostMapping</span><span class="token punctuation">(</span><span class="token string">"/login"</span><span class="token punctuation">)</span>
<span class="token keyword">public</span> JsonResult <span class="token function">login</span><span class="token punctuation">(</span><span class="token annotation punctuation">@RequestParam</span> String mobile<span class="token punctuation">,</span> <span class="token annotation punctuation">@RequestParam</span> String password<span class="token punctuation">,</span>
<span class="token annotation punctuation">@RequestParam</span> Integer age<span class="token punctuation">)</span><span class="token punctuation">{</span>
	<span class="token comment">//...</span>
    <span class="token keyword">return</span> JsonResult<span class="token punctuation">.</span><span class="token function">ok</span><span class="token punctuation">(</span>map<span class="token punctuation">)</span><span class="token punctuation">;</span>
<span class="token punctuation">}</span>

}

• 1
• 2
• 3
• 4
• 5
• 6
• 7
• 8
• 9
• 10
• 11
• 12
• 13
• 14
• 15
• 16
• 17

4、@ApiResponses、@ApiResponse：方法返回值的說明

@ApiResponses：方法返回對象的說明
	@ApiResponse：每個參數的說明
	    code：數字，例如400
	    message：信息，例如"請求參數沒填好"
	    response：拋出異常的類

• 1
• 2
• 3
• 4
• 5

示例：

@Api(tags="用戶模塊")
@Controller
public class UserController {
<span class="token annotation punctuation">@ApiOperation</span><span class="token punctuation">(</span><span class="token string">"獲取用戶信息"</span><span class="token punctuation">)</span>
<span class="token annotation punctuation">@ApiImplicitParams</span><span class="token punctuation">(</span><span class="token punctuation">{</span>
	<span class="token annotation punctuation">@ApiImplicitParam</span><span class="token punctuation">(</span>paramType<span class="token operator">=</span><span class="token string">"query"</span><span class="token punctuation">,</span> name<span class="token operator">=</span><span class="token string">"userId"</span><span class="token punctuation">,</span> dataType<span class="token operator">=</span><span class="token string">"String"</span><span class="token punctuation">,</span> required<span class="token operator">=</span><span class="token boolean">true</span><span class="token punctuation">,</span> value<span class="token operator">=</span><span class="token string">"用戶Id"</span><span class="token punctuation">)</span>
<span class="token punctuation">}</span><span class="token punctuation">)</span> 
<span class="token annotation punctuation">@ApiResponses</span><span class="token punctuation">(</span><span class="token punctuation">{</span>
	<span class="token annotation punctuation">@ApiResponse</span><span class="token punctuation">(</span>code <span class="token operator">=</span> <span class="token number">400</span><span class="token punctuation">,</span> message <span class="token operator">=</span> <span class="token string">"請求參數沒填好"</span><span class="token punctuation">)</span><span class="token punctuation">,</span>
	<span class="token annotation punctuation">@ApiResponse</span><span class="token punctuation">(</span>code <span class="token operator">=</span> <span class="token number">404</span><span class="token punctuation">,</span> message <span class="token operator">=</span> <span class="token string">"請求路徑沒有或頁面跳轉路徑不對"</span><span class="token punctuation">)</span>
<span class="token punctuation">}</span><span class="token punctuation">)</span> 
<span class="token annotation punctuation">@ResponseBody</span>
<span class="token annotation punctuation">@RequestMapping</span><span class="token punctuation">(</span><span class="token string">"/list"</span><span class="token punctuation">)</span>
<span class="token keyword">public</span> JsonResult <span class="token function">list</span><span class="token punctuation">(</span><span class="token annotation punctuation">@RequestParam</span> String userId<span class="token punctuation">)</span> <span class="token punctuation">{</span>
	<span class="token punctuation">.</span><span class="token punctuation">.</span><span class="token punctuation">.</span>
	<span class="token keyword">return</span> JsonResult<span class="token punctuation">.</span><span class="token function">ok</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">.</span><span class="token function">put</span><span class="token punctuation">(</span><span class="token string">"page"</span><span class="token punctuation">,</span> pageUtil<span class="token punctuation">)</span><span class="token punctuation">;</span>
<span class="token punctuation">}</span>

}

• 1
• 2
• 3
• 4
• 5
• 6
• 7
• 8
• 9
• 10
• 11
• 12
• 13
• 14
• 15
• 16
• 17
• 18
• 19

5、@ApiModel：用於JavaBean上面，表示一個JavaBean（如：響應數據）的信息

@ApiModel：用於JavaBean的類上面，表示此 JavaBean 整體的信息
			（這種一般用在post創建的時候，使用 @RequestBody 這樣的場景，
			請求參數無法使用 @ApiImplicitParam 註解進行描述的時候 ）	

• 1
• 2
• 3

5.1、@ApiModelProperty：用在JavaBean類的屬性上面，說明屬性的含義

示例:

@ApiModel(description= "返回響應數據")
public class RestMessage implements Serializable{
<span class="token annotation punctuation">@ApiModelProperty</span><span class="token punctuation">(</span>value <span class="token operator">=</span> <span class="token string">"是否成功"</span><span class="token punctuation">)</span>
<span class="token keyword">private</span> <span class="token keyword">boolean</span> success<span class="token operator">=</span><span class="token boolean">true</span><span class="token punctuation">;</span>
<span class="token annotation punctuation">@ApiModelProperty</span><span class="token punctuation">(</span>value <span class="token operator">=</span> <span class="token string">"返回對象"</span><span class="token punctuation">)</span>
<span class="token keyword">private</span> Object data<span class="token punctuation">;</span>
<span class="token annotation punctuation">@ApiModelProperty</span><span class="token punctuation">(</span>value <span class="token operator">=</span> <span class="token string">"錯誤編號"</span><span class="token punctuation">)</span>
<span class="token keyword">private</span> Integer errCode<span class="token punctuation">;</span>
<span class="token annotation punctuation">@ApiModelProperty</span><span class="token punctuation">(</span>value <span class="token operator">=</span> <span class="token string">"錯誤信息"</span><span class="token punctuation">)</span>
<span class="token keyword">private</span> String message<span class="token punctuation">;</span>
	
<span class="token comment">/* getter/setter 略*/</span>

}

• 1
• 2
• 3
• 4
• 5
• 6
• 7
• 8
• 9
• 10
• 11
• 12
• 13
• 14

http://localhost:5680/zxmall/swagger-ui.html

                                </div>