[TOC] > [home](http://apidocjs.com/) > [github](https://github.com/apidoc/apidoc) ## 概述 1. 夸語言生成腳本 2. 帶接口的版本管理 3. 可在接口文檔中執行(url 或表單提交) 4. 可繼承(如繼承錯誤返回實例) ## 安裝 `npm install apidoc -g ` `apidoc -i myapp/ -o apidoc/ -t mytemplate/ ` ## 教程 配置apidoc.json ``` { "name": "apidoc-example", "version": "0.4.0", "description": "apidoc example project", "title": "Custom apiDoc browser title", "url" : "https://localhost:8080", "header": { "title": "My own header title", "filename": "header.md" }, "footer": { "title": "My own footer title", "filename": "footer.md" }, "template": { "withCompare": true, //是否進行版本對比 "withGenerator": false, //是否輸出頁腳信息 "forceLanguage":"zh_cn" } } ``` ## 繼承(公用基礎模版) ### demo公用錯誤信息 `_apidoc.js` ``` /** * @apiDefine UserNotFoundError * * @apiError UserNotFound The id of the User was not found. * * @apiErrorExample Error-Response: * HTTP/1.1 404 Not Found * { * "error": "UserNotFound" * } */ ``` 調用 ``` /* * @apiUse UserNotFoundError */ ``` ## 版本設置 _apidoc.js ``` /** * @api {get} /user/:id Get User information * @apiVersion 0.1.0 * / ``` ``` /** * @api {get} /user/:id Get User information and Date of Registration. * @apiVersion 0.2.0 * / ``` ## 可識別 html 標簽 ``` @apiError UserNotFound The <code>id</code> of the <p>user</p> was not found. ``` ## 推薦模版 [https://github.com/EvandroViva/apidocjs\_template](https://github.com/EvandroViva/apidocjs_template) ## 接口說明 ### @apiDeprecated 棄用說明 ``` /** * @apiDeprecated use now (#Group:Name). * * Example: to set a link to the GetDetails method of your group User * write (#User:GetDetails) */ ``` > 如果需要在顯示接口文檔時,中文表示,`locales\zh_cn.js`,添加 `"DEPRECATED":"棄用" ### @apiError `@apiError [(group)] [{type}] field [description] ` #### demo 直接使用 ` @apiError UserNotFound3 ` #### 定義apiDefine _apidoc.js ``` /** * @apiDefine UserNotFound * @apiError (Error) {String} UserNotFound The <code>id</code> of the User was not found. */ /** * @apiDefine UrlNotFound2 * @apiError (Error) {String} UserNotFound2 The <code>id</code> of the User was not found. */ ``` ``` /* *@apiUse UserNotFound2 */ ``` ### @apiParam 請求參數 ``` //默認 @apiParam {Number} id this is a test //帶默認值 @apiParam {Number} id=123 this is a test //可選參數 @apiParam {Number} [id=123] this is a test //取值范圍 @apiParam {Number{100~900}} id this is a test @apiParam {String{2..5}} id this is a test //允許值 @apiParam {number=1,2,3} id this is a test @apiParam {string="small","huge"} id this is a test ``` ### @apiSuccess 返回參數 ``` //常規 @apiSuccess {String} firstname Firstname of the User. //設置組 @apiSuccess (code 200) {string} name this is name //設置第二層返回字段 @apiSuccess {Object} profile User profile information. @apiSuccess {Number} profile.age Users age. ``` ### @apiSuccessExample 成功示例 ``` @apiSuccessExample {json} 成功返回 { "firstname": "John", "lastname": "Doe" } ``` ### @apiExample 可用curl 做測試 ``` @apiExample {curl} Example usage: curl -i http://localhost/user/4711 ``` ### @apiPermission 權限設置 直接填寫 ``` @apiPermission admin ``` 添加說明 _apidoc.js ``` /** * @apiDefine admin 權限說明 * 只有admin用戶才可調用 */ ``` 調用 ``` @apiPermission admin ``` ### @apiErrorExample ``` /** * @api {get} /user/:id * @apiErrorExample {json} Error-Response: * HTTP/1.1 404 Not Found * { * "error": "UserNotFound" * } */ ``` #### demo `git clone https://github.com/apidoc/apidoc` ``` apidoc -i example -o doc -t template/ ``` ### @apiHeader header 信息 `@apiHeader {String} access-key Users unique access-key. ` ### @apiIgnore 忽略某個接口 ``` /** * @apiIgnore Not finished Method * @api {get} /user/:id */ ``` ### @apiPrivate 設置接口為私有值 ``` /** * @api {get} /user/:id * @apiPrivate */ ``` 普通編譯 忽略 `@apiPrivate` 通過 `apidoc ---private true` 取消忽略 ### @apiSampleRequest 可直接在文檔發送測試請求 > [詳情](http://apidocjs.com/#param-api-sample-request)