如果只是單純API要給前端或是其他單位或廠商串接
不希望專案裝太多API產生套件
只要Controller有根據APIDOC所規範註解
即可快速產生文件
不希望專案裝太多API產生套件
只要Controller有根據APIDOC所規範註解
即可快速產生文件
前置安裝
- 安裝`Node.JS`
- 安裝`APIDOC`套件
專案安裝APIDOC
npm install apidoc -g
執行產生APIDOC
- 開啟`CMD`, 並指向專案根目錄
- 執行即可產生
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 */