[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)