php apidoc 注释,apidoc 后端接口注释文档简单使用
apidoc使用指南
一、安装
# 全局安装
npm install apidoc -g
# 查看是否安装成功,显示命令行参数
apidoc -h
二、具体使用
# 1.在项目文件夹新建apidoc.json;
# 2.在项目根目录运行
# apidoc -i 源目录 -o 目标目录
apidoc -i ./router -o ./publish
# 简写指令
apidoc
说明：上面的指令可以直接简写为 apidoc，没有任何参数时，默认从当前目录(包括子目录)下格式为(.cs .dart .erl .go .java .js .php .py .rb .ts) 的所有文件生成文档并将输出写入 ./doc/。
三、基本配置
项目根目录下的 apidoc.json 可配置项包含有关项目的常用信息，如 标题，简短描述、版本和配置选项，如页眉/页脚设置或模板特定选项。
1.基本配置方式(apidoc.json)
{
"name": "user",
"version": "1.0.0",
"description": "用户操作接口文档",
"title": "user",
"url": "http://127.0.0.1:3000"
}
2.在含有package.json文件的项目中配置(添加"apidoc":{}参数)
{
"name": "example",
"version": "0.1.0",
"description": "apiDoc basic example",
"apidoc": {
"title": "Custom apiDoc browser title",
"url" : "https://api.github.com/v1"
}
}
四、使用
在相关接口上插入注释，例：
/**
* @api {get} /getuser 用户需求
* @apiVersion 1.0.0
* @apiGroup getUser
*
* @apiParam {String} id 用户id
* @apiParam {String} uname 用户名-非空
* @apiParam {String} uage 年龄
* @apiSuccess {Object} status 状态
* @apiSuccess {Object} msg 提示信息
* @apiSuccess {String[]} data 返回数据
*
* @apiSuccessExample {json} Success-Response:
* HTTP/1.1 200 OK
* {
* "status":0,
* "reason":"查询成功",
* "data":[]
* }
* @apiError UserNotFound The id of the User was not found.
*
* @apiErrorExample {json} Error-Response:
* HTTP/1.1 404 Not Found
* {
* "error": "UserNotFound"
* }
*/
router.get('/getuser', (req, res, next) => {
var sql = 'update user set ? where id=?';
var body = {
id: req.query.id,
uname: req.query.uname,
uage: req.query.uage
}
conn.query(sql, [body, body.id], (err, result) => {
if (err) console.log(result);
console.log(result);
})
})
再使用命令
apidoc -i ./router -o ./publish
即可生成接口文档，打开./publish/apidoc/index.html即可查看接口文档