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即可查看接口文档