快速產生 APIDOC 工具 RESTful web API

如果只是單純API要給前端或是其他單位或廠商串接
不希望專案裝太多API產生套件
只要Controller有根據APIDOC所規範註解
即可快速產生文件

前置安裝

安裝`Node.JS`
安裝`APIDOC`套件

專案安裝APIDOC

npm install apidoc -g

執行產生APIDOC

執行即可產生

apidoc -i MyProject/Controllers/ -o apidoc/

註解範例

/**
* @api {post} /Auth/Authenticate 取得 JWT Token
* @apiGroup 身分驗證
* @apiDescription 可取得登入Token
* @apiPermission none
* 
* @apiParam {String} MerchantNo 商戶號代碼
* @apiParam {String} MerchantKey 商戶號金鑰
* @apiParam {Number} UserID 用戶代碼
* @apiParam {String} UserName 用戶名稱
* 
* @apiParamExample {json} Request-Example:
*  {
*      "MerchantNo": "xxxxxx",
*      "MerchantKey": "xxxxxx",
*      "UserID": 9487,
*      "UserName": "我是誰"
*  }
*
* @apiSuccess {String} code 代碼
* @apiSuccess {String} message 訊息
* @apiSuccess {Object} data 資料
* @apiSuccess {String} data.merchantNo 商戶號代碼
* @apiSuccess {String} data.merchantKey 商戶號金鑰
* @apiSuccess {Number} data.userID 用戶代碼
* @apiSuccess {String} data.userName 用戶名稱
* @apiSuccess {String} data.token Token
* 
* @apiSuccessExample {json} Success-Response:
*  HTTP/1.1 200 OK
*  {
*      "code": 0,
*      "message": "登入成功",
*      "data": {
*          "merchantNo": "xxxxxx",
*          "merchantKey": "xxxxxx",
*          "userID": 9487,
*          "userName": "我是誰",
*          "token": "xxxxxx.xxxxxxxxxxxxxxxxxx.xxxxxxxxxxxxxxxxxx"
*      }
*  }
*  
*  @apiSuccessExample {json} Success-Response(維護中):
*  HTTP/1.1 200 OK
*  {
*      "code": 666,
*      "message": "維護中",
*      "data": null
*  }
*
* @apiSampleRequest /Auth/Authenticate
*/

/**
* @api {post} /Demo/GetUser 查詢用戶資料
* @apiGroup 用戶資料
* @apiDescription 查詢用戶資料
* @apiPermission JWT
* 
* @apiHeader {String} Authorization Bearer {your-token}
* @apiHeaderExample Header-Example:
*      "Authorization": "Bearer {your-token}"
* 
* @apiParam {String} UserID 用戶ID
* @apiParam {Object} Page 分頁
* @apiParam {Number} Page.Index 頁次 (起始為1; ex: 取資料量為10, 要取第11筆後資料, 頁次給2即可取11~20資料)
* @apiParam {Number} Page.Range 取資料量
* 
* @apiParamExample {json} Request-Example:
*  {
*      "UserID": 1,
*      "Page":{
*          "Index": 1,
*          "Range": 10
*      }
*  }
* 
* @apiSuccess {String} code 代碼
* @apiSuccess {String} message 訊息
* @apiSuccess {Object} data 資料
* @apiSuccess {String} data.UserID 用戶ID
* @apiSuccess {String} data.UserName 用戶名稱
* @apiSuccess {Date} data.UpdateTime 更新時間
* @apiSuccess {Object} data.Page 分頁
* @apiSuccess {Number} data.Page.index 目前頁次
* @apiSuccess {Number} data.Page.range 取資料量
* @apiSuccess {Number} data.Page.count 資料總筆數
*
* @apiSuccessExample {json} Success-Response:
*     HTTP/1.1 200 OK
*     {
*       "code": 0,
*       "message": "",
*       "data": [
*          {
*            "UserID": 1,
*            "UserName": "我是誰",
*            "updateTime": "2020/05/26 00:00:00.000"
*          }
*        ],
*        "page": {
*          "index": 1,
*          "range": 10,
*          "isNextPage": 0
*        }
*     }
*  
*  @apiSampleRequest /Demo/GetUser
*/