ApiDoc + github page 使用

你的項目在用什麼工具書寫api文檔？今天就來給大家推薦下ApiDoc

1. ApiDoc是什麼？

ApiDoc可以根據你再代碼裏的註釋，來生成api描述文檔，這樣就不用你自己去告訴端的小夥伴該怎麼調用你的api了。目前支持的變成語言有：Java，Javascript，Php，Python,C#,Ruby,Lua等，主流的編成語言都支持。

2. 怎麼用？

很簡單，只要在你的代碼裏用這樣的註解申明你的接口信息就好

/**
 * @api {get} /user/:id Request User information
 * @apiName GetUser
 * @apiGroup User
 *  * @apiParam {Number} id Users unique ID.
 *  * @apiSuccess {String} firstname Firstname of the User.
 * @apiSuccess {String} lastname  Lastname of the User.
 */

這裏面的這些註解都是ApiDoc定義好的，你只要按照官方文檔使用就好了。ApiDoc 官網

3. 開始搞起來

• 安裝

npm install apidoc -g

• 運行

apidoc -i api/ -o docs/

api是你的代碼目錄也就是你使用註釋的文件目錄，它會自動掃描使用註解的文件。docs文件時你要生成api文檔的目錄，也是github page最後要使用的目錄。

• 檢查api文檔

在docs目錄下直接打開index.html就可以查看最終結果了。

4. github page

github page 是一項免費的web服務，它允許你把你的靜態頁面發佈出去共其他用戶通過瀏覽器查看。剛纔我們生成的文檔內容都在我們本地，現在我們需要把它發佈到github上

• 創建github倉庫
• 將自己的生成後的戴阿曼上船，就是docs整個目錄
• 在倉庫的 setting中開啓page服務
• 用page提供的url去訪問

總結

ApiDoc提供了更好的api文檔閱讀體驗，對於開發者來說免去了寫文檔的麻煩。不過不足就是不能像swagger那樣提供在線調試，而且要想描述一個api需要些很多的註釋。