在開發介面的過程中，需要向外發布相應的介面文件。開始的時候使用word來寫文件，時間長了發現有幾個問題。
1. 編寫不方便。每次新增藉口的時候都要複製上乙個介面，然後再進行修改，一些相同的部分無法復用，介面多了文件會變的很長，還經常需要調整格式。
2. 發布不方便。文件更新時，需要發給需要的小夥伴。即使用git來進行管理，雖然拉取比較方便，但由於檔案格式的問題，也不方便比較兩次提交的差異。
由於有這些問題，決定尋找一種更優雅有效的方式來編寫文件。經過比較，發現了apidoc,可以比較好的解決上面提到的問題。apidoc採用了一種類似寫**注釋的方式來寫文件，支援編寫多種語言的文件。最後生成的文件以網頁的形式發布，方便快捷，便於閱讀。下面就來簡單介紹一下怎麼使用apidoc來寫文件。1. 由於apidoc依賴node.js的包管理工具npm進行安裝，所以安裝apidoc之前要先安裝node.js（npm會在安裝node時順帶進行安裝）。具體的安裝教程可以參考這裡。
2. 安裝完了npm之後，就可以安裝apidoc了。在命令列輸入
npm install apidoc -gapidoc -h/**
*@api /articles/:id 根據單個id獲取文章資訊
*@apiname 根據id獲取文章資訊
*@apigroup articles
* *@apiparam (params) id 文章id
* *@apisuccess article 返回相應id的文章資訊
* *@apierror (error 4xx) 404 對應id的文章資訊不存在
* *@apierrorexample error-response:
* http/1.1 404 對應id的文章資訊不存在
*
*/
/**
*@api path [title]
*/
描述method
請求的方法名稱：如get、post等等
path
請求路徑(只需要拼寫apidoc.json中配置位址的後面部分即可)
title(可選)
乙個簡短的標題（用於導航跟文件標題）
定於api歸屬的組名，生成的文件會把該api注釋歸類到該值對應的api組上。
/**
*@apigroup name
*/
描述name
歸屬組名稱
@apiname用於定義api文件的乙個例項，並用作例項名稱 。
/**
*@apiname name
*/
描述name
例項名稱
@apiparam用於編寫api的引數以及引數的解釋。
/**
*@apiparam [(group)] [field=defaultvalue] [description]
*/
描述(group) 可選
引數歸屬組名，不填寫組名，則預設設為paramter
可選引數資料型別，如、、等等
} 可選
變數的大小資訊 }引數型別為乙個字元不超過5的字串；}引數為乙個字元在2到5之間的字串；
可選引數允許值 引數只能接受small或者huge的字串
field 可選
引數名稱
=defaultvalue
引數預設值
description(可選)
描述@apiparamexample引數舉例
/**
*@apiparamexample [title]
* example
*/
描述 可選
請求資料結構
title 可選
例子的乙個簡短的標題
example
例子的詳細資訊，可多個例子並存
請求成功後的返回字段引數
/**
*@apisucces***ample [title] example
*/
描述(group) 可選
引數歸屬組名，不填寫組名，則預設設為success 200
可選返回的資料型別，如、等等
field
返回的標示符（返回成功的狀態碼）
description 可選
描述請求成功後返回的字段引數例子
/**
*@apisucces***ample [title] example
*/
描述 可選
請求資料結構
title 可選
例子的乙個簡短的標題
example
例子的詳細資訊，可多個例子並存
這個的用法跟@apisuccess、@apisucces***ample的用法相類似。
apiDoc 生成api文件
安裝node.js 安裝apidoc npm install apidoc g在你的專案根目錄下新建apidoc.json檔案，該檔案描述了專案對外提供介面的概要資訊如名稱 版本 描述 文件開啟時瀏覽器顯示標題和介面預設訪問位址。apidoc.json apidefine rknotfoundexc...
APIDOC 推薦乙個API生成器
一 apidoc 1 官網 2 頁面簡單 二 使用 安裝nodejs。然後npm install apidoc g 在自己的專案下新建乙個json檔名為 apidoc.json 案例 restcontroller users public class testcontroller test getb...
ApiDoc 自動生成API文件
1 確認已經安裝node.js 可以使用npm命令 否則要先安裝node 2 安裝apidoc 命令列執行 npminstall apidoc g 3 在專案的當前目錄下編寫乙個指令碼genapidoc.bat 內容為 apidoc o doc apidoc pause 將生成的api文件 o 輸出...