在開發接口的過程中，需要向外發布相應的接口文檔。開始的時候使用word來寫文檔，時間長了發現有幾個問題。
- 編寫不方便。每次新增借口的時候都要復制上一個接口，然后再進行修改，一些相同的部分無法復用，接口多了文檔會變的很長，還經常需要調整格式。
- 發布不方便。文檔更新時，需要發給需要的小伙伴。即使用git來進行管理，雖然拉取比較方便，但由于文件格式的問題，也不方便比較兩次提交的差異。
由于有這些問題，決定尋找一種更優雅有效的方式來編寫文檔。經過比較，發現了apidoc 可以比較好的解決上面提到的問題。
apidoc采用了一種類似寫代碼注釋的方式來寫文檔，支持編寫多種語言的文檔。最后生成的文檔以網頁的形式發布，方便快捷，便于閱讀。下面就來簡單介紹一下怎么使用apidoc來寫文檔。
1.安裝node
由于apidoc依賴node.js的包管理工具npm進行安裝，所以安裝apidoc之前要先安裝node.js（npm會在安裝node時順帶進行安裝）。具體的安裝教程可以參考這里。
2.安裝apidoc
安裝完了npm之后，就可以安裝apidoc了。在命令行輸入
npm install apidoc -g
就可以進行安裝了。
安裝完成輸入
apidoc -h
出現相關的提示幫助信息，說明安裝成功了。
3 apidoc 常用注解介紹
apidoc是運用各個不同的注解來完成文檔的寫作的。學習apidoc，主要就是學習注解的用法。apidoc和命名行的命令很像，由一個注解關鍵字加一些選項構成。下面介紹一下apidoc主要的注解。
@api {method} path [title]
這是apidoc必需的注解，用來說明api的方法，訪問路徑和作用。
@apiParam [(group)] [{type}] [field=defaultValue] [description]
這個注解用來說明api請求參數的類型，大小和作用。
@apiSuccess [(group)] [{type}] field [description]
這個注解說明api返回參數的類型，大小和作用。
關于注解的詳細用法可以訪問官網，上面有詳細的用法和示例。
4.編寫apidoc文檔
了解了關于注解的用法之后，就可以用注解來編寫文檔了。例如我們可以編寫一個GetUser.java文件。里面的內容如下所示：
/**
* @api {get} /user/:id Request User information
* @apiGroup User
*
* @apiParam {Number} id Users unique ID.
*
* @apiSuccess {String} firstname Firstname of the User.
* @apiSuccess {String} lastname Lastname of the User.
*/
5 生成apidoc文檔
編寫完成后，運行
apidoc -i apidocIn -o apidocOut
apidocIn表示GetUser.java文件的存放目錄，apidocOut表示希望apidoc文檔生成的目錄。運行成功后，在輸出目錄可以看見一堆生
成的文件，其中index.html是我們需要的文檔。在瀏覽器打開就可以看見效果了。效果如下圖所示：
后面可以配置一下nginx，指定訪問的路徑映射到index.html，就可以讓需要文檔的小伙伴們訪問了。
