ApiDoc使用及操作文档
首先安装node.js
下载最新版node.js 安装node.js
https://nodejs.org/en/
判断node.js和npm是否安装正常
node -v npm -v
安装ApiDoc,最好使用git安装
npm install apidoc -g
查看ApiDoc是否安装成功
apidoc -v
安装成功之后，在项目更目录创建文件apidoc.json (文件创建之后删除所有注释)
{ "name": "appleFarm", //文档项目名 "title": "appleFarmAPI", //html标题 "description":"appleFarmAPI接口文档", //文档描述 "url" : "https: //xxx.com",//公共接口地址 "version": "0.1.0" //文档版本 }
写好注释之后在更目录输入命令
apidoc -i Application/ -o apidoc/
Application 为注释目录文件夹 apidoc为新建apidoc输出目录
注释例子：
/** * @api {post} /tanfangri/get-by-id 根据戒毒所ID取内容 * @apiDescription * @apiVersion 0.1.0 * * @apiParam {string} jiedusuo_id 戒毒所ID * * * @apiGroup tanfangri * * @apiSuccessExample * { "code": 1, "message": "相关内容" } */
注释说明
@api {get} /users/:user_id Request User Information
最主要的参数，”{get}”定义了HTTP请求是GET，API地址是”/users/:user_id”，文档中API的名称是”Request User Information”。
@apiVersion 0.1.0
API的版本号，默认显示在API名称的右方。该参数可用来在不同的版本之间做比较，后面会介绍。
@apiName GetUser
API名称，不影响文档。
@apiGroup User
API分组名，文档内容中和菜单栏中同一组的API会在一同显示，方便阅读。
@apiPermission admin
API的访问权限，文档中默认会API地址下面显示。没有权限要求的话，此项可以省略。
@apiDescription API to get the user information.
API的详细描述，默认显示在API名称的下方。
@apiExample Example usage:
API调用示例，该参数的下一行就是示例的内容，直到有空行结束。可以定义多个@apiExample，默认在文档中会以标签形式列出，标签名就是”Example usage:”。
@apiParam {Number} user_id The user’s unique ID.
API参数字段介绍，”{Number}”定义了字段类型，”user_id”是字段名称，后面则是字段描述。可以定义多个@apiParam字段。
@apiSuccess {String} name Name of the User.
API成功后返回的字段，如同@apiParam，”{String}”定义了字段类型，”name”是返回字段名称，后面则是字段描述。可以定义多个@apiSuccess字段。
@apiSuccessExample {json} Success-Response:
显示一个API成功返回后Response响应的示例，”{json}”代表响应体是JSON类型。该参数的下行就是响应体内容，直到有空行结束。可以定义多个@apiSuccessExample，默认在文档中会以标签形式列出，标签名就是”Success-Response:”。
@apiError UserNotFound User was not found.
API发生错误后的返回，”UserNotFound”是错误名称，后面则是错误描述。可以定义多个错误返回。
@apiErrorExample {json} Error-Response:
显示一个API错误返回后Response响应的示例，”{json}”代表响应体是JSON类型。该参数的下行就是响应体内容，直到有空行结束。可以定义多个@apiErrorExample，默认在文档中会以标签形式列出，标签名就是”Error-Response:”。
@apiSampleRequest http://localhost:5000/users/:user_id
文档提供的API Sample测试的地址。其实在”apidoc.json”中配过”sampleUrl”项后，此参数即可省去，除非这个API的测试URL比较特殊，需特别指定。
