使用背景 :

由於後端介面開發好，提供介面文件供前端人員呼叫；由於某種原因，修改了介面，文件沒有及時更新，導致後續交接或聯調時介面文件不匹配；使用apidoc文件自動生成工具，解決這一問題。

方案介紹 :

apidoc是基於node語言寫的介面文件生成工具。

特點：

• 適用於多種語言，包括並不限於 java、node、php、c#等語言

• 與業務程式碼無耦合，直接修改註釋的格式即可

• 介面文件是HTML頁面，簡潔明瞭

git地址：

https://github.com/apidoc/apidoc

使用步驟 :

1）環境安裝

• 安裝node執行環境和npm第三方包

• 安裝apidoc模組，執行命令 npm install apidoc -g

2）專案接入apidoc（舉例 基於 javaweb 微信公眾號專案）

安裝好環境之後，在專案的根目錄建立檔案apidoc.json

開啟apidoc.json進行編輯

對應的頁面效果

3）程式碼註釋說明

定義一個全域性屬性，變數名在整個專案中不能重複（一處定義，四處引用） @apiDefine 變數名 變數說明 詳細說明

示例： @apiDefine statistic 統計模組 微信管理員檢視相關指標，粉絲分佈情況，場景二維碼建立情況，自定義選單使用情況等等

定義其他全域性變數

4）介面程式碼 註釋及詳情示例，括號裡面是說明

5）生成介面文件

使用技巧

後端專案加入git管理，專案使用自動構建工具(如Jenkins); 

當開發人員提交程式碼到git裡，Jenkins會 監聽是否有程式碼提交，一旦發現有程式碼傳送變化，則執行對應的shell指令碼.。

我們在shell腳本里面執行apidoc構建命令，並把構建好的文件傳輸到統一的文件伺服器，配置域名，專案組的人就能訪問到最新的文件。

關於apidoc詳情，請參考資料 相關資料： 

英文官網：http://apidocjs.com/#install 

長按圖片識別圖中二維碼(或搜尋微信公眾號FrontEndStory