工具名称:apiDoc
Git地址:https://github.com/apidoc/apidoc
项目地址:http://apidocjs.com/
样例项目:http://apidocjs.com/example_basic/
一、安装apidoc模块
apidoc是nodejs模块,github上有安装和使用说明。
# npm install apidoc -g
二、在代码文件夹的根目录下,创建apidoc.json文件
{
"name": "xx平台",
"version": "0.1.0",
"description": "为您提供优质的数据服务",
"title": "xx平台",
"url" : "http://127.0.0.1:8080/demo"
}
三、在代码文件夹的根目录下,创建build.bat
apidoc -i e:/nodejs/myapp/ -o e:/nodejs/myapp/apidoc/
eg:
apidoc -f ".*\\.js$" -f ".*\\.java$" -i myapp/ -o apidoc/ -t mytemplate/
参数说明:
-f 文件过滤
-i 代码文件夹
-o 输出Api文档的路径
-t 使用模板文件的路径,可以自定义输出的模板
tips:
参数名称加[name],表示可选参数。
四、参考
/**
* @apiDefine name 名称匹配
*/
/**
* @apiDefine pub_params
* @apiParam {string} accesskey 授权凭证
* @apiParam {string} timestamp 时间戳
* @apiParam {string} random 随机数
* @apiParam {string} digest 签名
*/
/**
* @api {POST} /bank/api/basicQuery.json 根据地址查询
* @apiGroup name
* @apiName 根据地址查询
* @apiVersion 1.0.0
* @apiHeader {String} ContentType=application/json;charset=UTF-8 ContentType
* @apiHeader {String} Accept=application/json;charset=UTF-8 Accept
*
* @apiUse pub_params
*
* @apiParam {string} name 名称
* @apiParam {string} [province] 省份
* @apiParam {string} [city] 城市
*
* @apiParamExample {json} paramExample:
* {
* "accesskey":"xxxxxxxxxxxxxxxxxxxxxx",
* "timestamp":"1552302151",
* "random":"xxxxxxxxxxxxxxxxxxxxxx",
* "digest":"xxxxxxxxxxxxxxxxxxxxxx",
* "message":"{\"name\":\"北部工业区\",\"province\":\"河北\",\"city\":\"岛市\",\"pageNumber\":1,\"pageSize\":10}"
* }
*
* @apiSuccess {string} responseCode 状态码:0.成功、-1.非法请求、-2.签名错误、-51.未知错误、
* @apiSuccess {string} responseMessage 响应提示信息
* @apiSuccess {string} bank_type x行
* @apiSuccess {string} city 城市
* @apiSuccess {string} code 号
* @apiSuccess {string} name 名称
* @apiSuccess {string} province 省份
*
* @apiSuccessExample {json} Response (success):
* {
* "accesskey": "xxxxxxxxxxxxxxxxxxxxxx",
* "secretKey": null,
* "timestamp": "20190307062545",
* "random": "xxxxxxxxxxxxxxxxxxxxxx",
* "digest": "xxxxxxxxxxxxxxxxxxxxxx",
* "responseCode": 0,
* "responseMessage": "成功"
* }
* @apiErrorExample Error-Response:
* {
* "accesskey": "xxxxxxxxxxxxxxxxxxxxxx",
* "secretKey": null,
* "timestamp": "20190307062545",
* "random": "xxxxxxxxxxxxxxxxxxxxxx",
* "digest": "xxxxxxxxxxxxxxxxxxxxxx",
* "responseCode": -1,
* "responseMessage": "非法请求"
* }
*/