1調研背景

目前存在以下情況:

1）一般開發人員更新介面後，沒有同時更新rap，rap上的介面定義普遍存在跟程式碼不一致的情況。

2）後端開發人員檢視別人介面，很難很快地知道介面的作用，以及介面入參和返回結果中每個欄位的含義。

3）rap上的mock資料功能不是特別好用。

2 調研結果

為了解決以上問題，調研了主流的三個工具，swagger2、spring rest docs、apidoc

基於以下原則對軟體做了篩選：

1）不允許使用註解（annotation），對程式碼侵入性比較強， 排除swagger2

2）不執行java程式就能生成文件，排除spring rest docs

3）可以給前端提供mock資料

所以採用了apidoc

參考文章：

 用spring Restdocs建立API文件   http://blog.csdn.net/forezp/article/details/71023510

 springboot整合swagger2，構建優雅的 Restful API http://blog.csdn.net/forezp/article/details/71023536

 springboot整合apidoc     http://blog.csdn.net/forezp/article/details/71023579

3 apidoc實施方案：

1） 測試環境部署統一的api文件伺服器，目錄按專案劃分,訪問路徑: http://docs. ***.com/api/專案名/

2） 開發人員按照apidoc的規則對介面寫詳細的註釋

3） 提交程式碼後，Jenkins執行gradle apidocs命令生成html檔案，然後上傳到伺服器對應的目錄中

4 專案參考案例

專案：[email protected]***.com:wy-serverside/insurance-2b-group.git

文件：http://docs. ***.cn/api/insurance-2b-group/

Jenkins任務：test_insurance_2b_group

apidoc便捷生成工具：http://tool.suiyiwen.com/apidoc/

5 後端開發本地環境配置

5.1 Apidoc安裝

首先需安裝nodejs，然後安裝apidoc(執行npm install apidoc –g)

5.2 專案配置

5.2.1 gradle專案的配置檔案build.gradle增加配置

1. def isWindows(){
2. return org.gradle.internal.os.OperatingSystem.current().isWindows()
3. }
4. String apidocCmd = isWindows()?'apidoc.cmd':'apidoc'
5. task apidocs(type:Exec, description:'執行生成apidoc文件操作'){
6. workingDir './'
7. def docCommand =[apidocCmd,'-o','./build/apidocs']
8. commandLine docCommand
9. }

5.2.2專案的根目錄增加檔案apidoc.json

1. {
2. "name":"springboot-sample介面文件",
3. "version":"1.0.0",
4. "description":"",
5. "title":"springboot-sample",
6. "url":"https://demo.test.com"
7. }

5.2.3 Controller根據apidoc的規範增加註釋（ http://apidocjs.com/）

1. /**
2. * @apiVersion 1.0.0
3. * @api {GET} /group/front/getOutlinePaySuccessInfo 獲取支付成功資料
4. * @apiGroup TransferAccount
5. * @apiName getOutlinePaySuccessInfo
6. * @apiParam (請求引數) {String} orderID 訂單號
7. * @apiParam (請求引數) {String} partnerCode 渠道code
8. * @apiParam (請求引數) {String} sign 簽名
9. * @apiParamExample 請求引數示例
10. * ?orderID=G0000168752925895356416&partnerCode=wyxx&sign=064d8cc51ed0957839e62f6684a4fe5c
11. * @apiSuccess (響應引數) {String} accountName 收款人
12. * @apiSuccess (響應引數) {Number} insuredNum 被保人數量
13. * @apiSuccess (響應引數) {String} returnUrl 跳轉地址（可能為空）
14. * @apiSuccess (響應引數) {Number} validStartDate 開始時間
15. * @apiSuccess (響應引數) {Number} validEndDate 截止時間
16. * @apiSuccessExample 響應示例
17. * {"code":200,"msg":"成功","data":{"groupName":"微易測試","insuredNum":5,"returnUrl":"http://www.baidu.com","validStartDate":1524127875000,"validEndDate":1524127875000}}
18. */

5.2.4 本地執行gradle apidocs，生成文件

5.2.5  其他：idea註釋模板使用

1）Settings-->editorLive Templates 新增模板

2）Abbreviation設定為apidoc

3）Context type設定為java:declaration

4）勾選Reformat according to stype

5）新增模板內容

6）Java檔案中輸入apidoc使用

1. /**
2. * @apiVersion 1.0.0
3. * @api {method$END$} path title
4. * @apiGroup name
5. * @apiName name
6. *
7. * @apiParam (請求引數) {type} field description
8. * @apiParam (請求引數) {type} field=defaultValue description
9. * @apiParamExample 請求引數示例
10. * example
11. *
12. * @apiParam (請求體) {type} field description
13. * @apiParam (請求體) {type} field=defaultValue description
14. * @apiParamExample 請求體示例
15. * example
16. *
17. * @apiSuccess (響應引數) {type} field description
18. * @apiSuccess (響應引數) {type} field description
19. * @apiSuccessExample 響應示例
20. * example
21. *
22. */

文章出自：http://blog.suiyiwen.com/post/4