apidoc 生成Restful web Api文檔

在項目開發過程當中，總會牽扯到接口文檔的設計與編寫，以前使用的都是office工具，寫一個文檔，總也是不夠漂亮和直觀。好在git上的開源大神提供了生成文檔的工具，so來介紹一下！ 
該工具是Nodejs的模塊，請務必在使用前安裝好nodejs環境！

一．安裝Apidoc

1.安裝nmp環境,Windows環境可直接經過http://nodejs.org/下載安裝包安裝

2.安裝後在cmd終端執行npm install apidoc –g若是執行失敗跳到步驟3

3.安裝npm首先先安裝Homebrew在終端ruby -e "$(curl –fsSL

https://raw.githubusercontent.com/Homebrew/install/master/install)"

4.執行成功終端輸入brew install node等待一段時間

5.執行成功終端輸入npm –v確認是否npm安裝成功

6.安裝npm成功後執行執行npm install apidoc –g 安裝apidoc便可。

二．apidoc使用

1.在項目根目錄中建立apidoc.json文件

{
  "name": "Apidoc Example",
  "version": "1.0.0",
  "description": "Apidoc Example descrption",
  "title": "Custom apiDoc browser title",
  "url" : "http://localhost:8080/v1",
  "sampleUrl": "http://localhost:8080/v1",
  "forceLanguage":"zh-cn",
  "template": {
   "withCompare": true,
   "withGenerator": true
  }
}

2.在對應接口上加上註釋:

示例:

/**
 *
 * @api {post} /m/login.do  登陸
 * @apiName 登陸
 * @apiGroup login
 * @apiVersion 1.0.0
 * @apiDescription 接口詳細描述
 *
 * @apiParam {String} username 用戶名
 * @apiParam {String} password 密碼
 *
 * @apiSuccess {String} status 結果碼
 * @apiSuccess {String} msg 消息說明
 * @apiSuccessExample Success-Response:
 *  HTTP/1.1 200 OK
 * {
 * status:0,
 * msg:'success',
 * data:{}
 *  }
 *
 *  @apiError All 對應<code>id</code>的用戶沒找到
 *  @apiErrorExample {json} Error-Response:
 *  HTTP/1.1 200
 *  {
 *   code:-1,
 *   msg:'user not found',
 *   }
 */

3.執行終端命令apidoc -i example/ -o doc/執行成功就則會在該目錄下生成doc文件。

// 典型用法
apidoc -i api/ -o doc/api [-c ./] -f ".*\.js$"

-i 表示輸入，後面是文件夾路徑
-o 表示輸出，後面是文件夾路徑
默認會帶上-c，在當前路徑下尋找配置文件(apidoc.json)，若是找不到則會在package.json中尋找 "apidoc": { }
-f 爲文件過濾，後面是正則表達式，示例爲只選着js文件
  與-f相似，還有一個 -e 的選項，表示要排除的文件/文件夾，也是使用正則表達式

示例:

apidoc -i e:\example -o e:\doc

這樣就會在e:\doc目錄下生成項目的doc文檔,點開index.html就會看到以下效果

 

三．apidoc代碼註釋

apidoc支持以下關鍵字

@api {method} path [title]
  只有使用@api標註的註釋塊纔會在解析以後生成文檔，title會被解析爲導航菜單(@apiGroup)下的小菜單
  method能夠有空格，如{POST GET}
@apiGroup name
  分組名稱，被解析爲導航欄菜單
@apiName name
  接口名稱，在同一個@apiGroup下，名稱相同的@api經過@apiVersion區分，否者後面@api會覆蓋前面定義的@api
@apiDescription text
  接口描述，支持html語法
@apiVersion verison
  接口版本，major.minor.patch的形式

@apiIgnore [hint]
  apidoc會忽略使用@apiIgnore標註的接口，hint爲描述
@apiSampleRequest url
  接口測試地址以供測試，發送請求時，@api method必須爲POST/GET等其中一種

@apiDefine name [title] [description]
  定義一個註釋塊(不包含@api)，配合@apiUse使用能夠引入註釋塊
  在@apiDefine內部不能夠使用@apiUse
@apiUse name
  引入一個@apiDefine的註釋塊

@apiParam [(group)] [{type}] [field=defaultValue] [description]
@apiHeader [(group)] [{type}] [field=defaultValue] [description]
@apiError [(group)] [{type}] field [description]
@apiSuccess [(group)] [{type}] field [description]
  用法基本相似，分別描述請求參數、頭部，響應錯誤和成功
  group表示參數的分組，type表示類型(不能有空格)，入參能夠定義默認值(不能有空格)
@apiParamExample [{type}] [title] example
@apiHeaderExample [{type}] [title] example
@apiErrorExample [{type}] [title] example
@apiSuccessExample [{type}] [title] example
  用法徹底一致，可是type表示的是example的語言類型
  example書寫成什麼樣就會解析成什麼樣，因此最好是書寫的時候注意格式化，(許多編輯器都有列模式，能夠使用列模式快速對代碼添加*號)

@apiPermission name
  name必須獨一無二，描述@api的訪問權限，如admin/anyone

詳細文檔參考http://caixw.oschina.io/apidoc/