apidoc文檔項目構建

時間 2019-11-08

標籤 apidoc 文檔項目構建简体版

原文原文鏈接

安裝全局依賴apidoc

npm install apidoc -g複製代碼

建立項目目錄

建立src文件夾，並建立apidoc.json文件

{  
    "name": "項目名稱",  
    "version": "1.0.0",  
    "description": "項目名稱- 接口文檔",  
    "title": "項目名稱",  
    "url" : "http://localhost:8080/api",  
    "sampleUrl": "http://localhost:8080/api",  
    "header": {    
        "title": "頂部說明",    
        "filename": "header.md"  
    },  
    "footer": { 
       "title": "底部說明",
       "filename": "footer.md"  
    },  
    "order": [
        "Error",
        "Define",
        "PostTitleAndError",
        "PostError"  
    ]
}複製代碼

src下建立footer.md

底部說明
1. 底部具體內容說明複製代碼

src下建立header.md

頂部說明
1. 頂部具體內容說明複製代碼

建立public.js文件，用來描述接口的文檔js，簡單描述說明：

@apiDefine 用來定義變量
@apiGroup 歸類接口組別
@apiDescription 接口描述
@apiName 接口名稱
@apiPermission 接口須要的權限（token）
@apiParam 接口參數
@apiHeaderExample 接口Headers請求參數實例

@apiSuccess 成功響應

/** 
 * @apiDefine personalGroup 我的信息 
 */

/**
 * @api {post} /v1/register 註冊
 * @apiName register
 * @apiGroup personalGroup
 * @apiDescription 用戶註冊
 *
 * @apiParam {String} mobile 手機號
 * @apiParam {String} password 密碼.
 * @apiParam {Int} sms_code 驗證碼.
 * @apiParam {Int} invite_code 邀請碼.
 *
 * @apiSuccess (200) {Number} status 狀態碼 10000表示陳功.
 * @apiSuccess (200) {String} msg  提示語.
 * @apiSuccess (200) {Json} data 返回數據.
 */

/**
 * @api {get} /v1/account 獲取資產
 * @apiName getAccount
 * @apiGroup publicGroup
 * @apiPermission token
 *
 * @apiParam (headers參數) {String} token 在請求頭headers中添加token信息
 *
 * @apiHeaderExample {json} Headers:
 *     {
 *       "Content-Type": "application/json;charset=UTF-8",
 *       "token":"sfdasd"
 *     }
 * @apiSuccessExample {json} 正確響應：
 * HTTP/1.1 200 OK
 * {
 *     status:10000,
 *     msg:"發送成功",
 *     data:{
 *         ...
 *     }
 * }
 * @apiSuccess (200) {number} status 狀態碼 10000表示陳功.
 * @apiSuccess (200) {String} msg  提示語.
 * @apiSuccess (200) {String} data 返回數據.
 */
複製代碼