本文主要講述自動化API文檔生成——apidoc。網上有幾個篇文章都只是介紹apidoc的，具體怎么在自己的項目中使用以及與其他配合使用都是沒介紹的。最近開始玩服務器，了解到了有Windows與Linux之間共享文件的方法，就是samba。然后具體和apidoc結合起來非常好用，所以本文就當做筆記來把它記錄下來了
_

apidoc簡介

　　apidoc是node的一個插件，它的功能就是能讓把我們的代碼注釋生成api文檔。它支持php java javascript python等多中語言。因為寫接口的同學通常很煩寫完接口還得寫文檔，文檔更新又麻煩。apidoc不僅支持項目的版本，也支持api的版本。在我所接觸過的文檔生成工具里面，這個是我感覺比較好用的。
_

apidoc的安裝

　　apidoc是node的一個插件，那么它的安裝就依賴node。node的具體安裝我這里就不詳細說了，去node官網下包,解壓，編譯然后安裝。直接執行:

npm install apidoc -g 

_

samba的安裝

　　samba的安裝也很簡單，本人用的是CentOS，我直接執行

yum install samba

就安裝好了。
_

samba的配置

        [public]comment = Public Stuffpath = /share/doc  你需要共享文件夾的路徑browseable = yes  可瀏覽性 guest ok = yes  是否允許訪客public = yes  是否可上傳writable = yes  是否可寫

我自己裝的時候也都是這么配置的，注意，這個samba需要你關閉你的防火墻，還得把你共享的目錄賦予777的權限（貌似755就夠了，我直接給了777）。我這邊還遇到過一個很坑爹的問題，就是這樣配置了，用Windows訪問這個共享目錄的時候，要求我輸入用戶名和密碼。其實主要還得把上面的

security = user

改成

security = share

samba也是支持用戶管理的，就是可以分配賬號密碼的，具體的就不展開介紹了。
_

apidoc的使用

　　例如我們在代碼里面下了這樣的一段注釋:

/*** @api {get post} /brand/:id/:name/:new 這里中括號里面填的的是請求方式（GET POST OPTION DELETE等），后面填的是路由* @apiGroup brandList API接口所在的組名稱* @apiName  brands  API接口名稱* @apiVersion 1.0.1 API接口版本* @apiDescription  API接口的描述** @apiParam (入參) {Number{1-9999}}()這個括號里面的天的參數的組，括號里面相同的會被放在同一個表格里面 id=0 請求參數 大括號里面填的是參數類型 里面的大括號表示值的范圍 后面就是參數的名稱和默認值* @apiParam (入參) {String="a","b","c"} name 品牌名稱,等于號表示允許值* @apiParam (入參) {Boolean} new * @apiParam (入參) {Number} [test] 如果參數套上[]這樣的中括號，表明這個值是個可選的值** @apiParamExample {json} 接口返回值* {*     "code" : 0,*     "message" : "success",*     "data" : {*         "result" : "ok"*     }* }* @apiSampleRequest  下面就是一個模擬請求器，可以幫我們調試接口*     http://www.work.dev**/

基本上用這些已經足夠了，其他的用法可以參考它的官網:http://apidocjs.com/
_

生成apidoc

　　假如我在我的控制器里面寫了這樣一段注釋:

 /**
* @api {GET} /user_info 獲取用戶信息接口
* @apiGroup User
* @apiVersion 2.0.0
* @apiDescription 獲取用戶信息
*
* @apiParam (入參) {String} token 登錄成功后客戶端返回的token
*
* @apiSuccessExample Success-Response:
*  {
*      "code": 0,
*      "message": "ok"
*      "data": {
*           "name": "1",//狀態 0:啟用 1:停用
*           "role": "1",//1管理員，0是普通員工
*           "sex": "1",//1表示男性，2表示女性
*      }
*  }
*
* @apiSampleRequest
* http://api.test.com/user_info
*
*/

先cd到項目里面
然后執行這樣的語句:

apidoc -i app/Http/Controllers -o \\115.28.231.211\public\

因為我samba共享的是這樣一個文件夾，并且在這個里面放文檔。然后我們來看下生成的結果

這時候我們直接點擊index.html可以直接看到這樣的靜態頁面:

_

后話

　　到這里，我們就已經很方便的能運用apidoc了，我們可以自己直接寫好接口的時候直接寫注釋，一句命令寫到開了samba的服務器上，然后直接訪問靜態頁面，如果不想這樣赤裸裸的訪問靜態頁面，可以用node或者nginx直接綁上去，這里就不繼續展開講了。
_

后續補充

　　其實在使用中的時候會發現一些很坑爹的問題，就是GroupName沒法用中文，但是其他地方可以用中文。畢竟這個是國外大佬發明的，不是國人的產物，有存在這樣的問題也在所難免。我不斷的搜，發現github上有人給他提issure。也有給出了解決方案，apidoc的語法其實是支持引用的，所以我們可以這樣定義

/*** @apiDefine name 測試中文*/

然后我們怎么使用呢。可以直接@apiUse name 也可以直接在注釋里面寫name,這樣就可以使用中文了。

　　<font color='red'>這個東西唯一讓我不爽的就是有可能一大段注釋只是為了生成接口文檔！！！其它真的很好用</font>