API文檔自動生成

本文主要講述自動化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 Stuff
        path = /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>