Spring MVC中使用Swagger生成API文件和完整專案示例Demo,swagger
轉載自:http://www.360doc.com/content/17/0914/17/16915_687184334.shtml
實際專案中非常需要寫文件,提高Java服務端和Web前端以及移動端的對接效率。 聽說Swagger這個工具,還不錯,就網上找了些資料,自己實踐了下。
一:Swagger介紹 Swagger是當前最好用的Restful API文件生成的開源專案,通過swagger-spring專案 實現了與SpingMVC框架的無縫整合功能,方便生成spring restful風格的介面文件, 同時swagger-ui還可以測試spring restful風格的介面功能。
官方網站為:http://swagger.io/
二:Swagger與Spring MVC整合步驟
1.Maven關鍵配置
[html] view plain copy
2. 外掛配置 CustomJavaPluginConfig
3.複製swagger的相關js等靜態資源到webapp目錄。 swagger-ui.js之類的。 我copy過一次,但是有問題,最後從網上下載了一個專案,可以直接用的那種。 然後自己再逐步改造。
4.啟動專案
三、常見swagger註解一覽與使用 最常用的5個註解@Api:修飾整個類,描述Controller的作用 @ApiOperation:描述一個類的一個方法,或者說一個介面 @ApiParam:單個引數描述
@ApiModel:用物件來接收引數 @ApiProperty:用物件接收引數時,描述物件的一個欄位
其它若干
@ApiResponse:HTTP響應其中1個描述 @ApiResponses:HTTP響應整體描述
@ApiClass @ApiError @ApiErrors
@ApiParamImplicit @ApiParamsImplicit
四、關鍵程式碼和實際例子 例子1: [java] view plain copy
@ApiParam(value = "token", required = true) @RequestParam String token Web前端/移動端HTTP請求方式:直接把引數附帶到URL後面,或者用AJAX方法,表單提交。
例子2: [java] view plain copy
當引數太多的時候,需要定義太多的引數,排版看起來很不舒服。 這個時候,可以使用物件來接收。 @ApiModel(value = "使用者物件",description="user2") public class User extends CommonParam{
} Web前端/移動端HTTP請求方式:直接把引數附帶到URL後面,或者用AJAX方法,表單提交。 這裡面存在一個小問題,當後端用物件User來接收引數的時候,Swagger自帶的工具是這樣的:
這種形式,並不是表單提交,或者把引數附加到URL的後面。 我們只能手動構造URL,附帶引數去提交。 如果需要測試的話!
例子3: [java] view plain copy
Web前端/移動端HTTP請求方式:必須把引數,放到request請求的body中去。 後端不能直接用request.getParam("token")這種。
獲得request body中的資料,手動轉換成目標資料。 String charReader(HttpServletRequest request) throws IOException {
BufferedReader br = request.getReader();
String str, wholeStr = ""; while ((str = br.readLine()) != null) { wholeStr += str; } return wholeStr;
}
個人推薦: 1.引數不多的時候,用例子1,用@ApiParam註解生成文件。 swagger視覺化介面,可以直接設定引數,傳送請求來測試 2.引數比較多的時候,用例子2,用物件來接收引數,在物件裡針對每個欄位,@ApiModelProperty註解生成文件。 swagger視覺化介面,可以直接設定引數,但是無法接收到。 因此,推薦使用其它HTTP請求或POST模擬工具,傳送請求,模擬測試。
不推薦例子3,不通用,侷限性比較大。
五、若干截圖
六、原始碼 [java] view plain copy
[java] view plain copy
[java] view plain copy
|