登录

使用apidoc自动生成api文档

PHP 置顶
0 777

apidoc是一个轻量级的在线REST接口文档生成系统,可以根据其特定的规则的代码注释来生成静态网页。首先看下它生成的文档界面和风格。

安装和配置apidoc
首先要确认你的系统安装了nodejs,然后执行npm install -g apidoc
配置apidoc,在你的项目下创建apidoc.json文件,apidoc.json说明

1
2
3
4
5
6
7
8
{
"name""测试APIs",
"version""1.0.0",
"description""接口测试",
"title""test APIs",
}

使用
apidoc是根据其自定义注释语法来生成文档的,语法可参考apidoc Params
下面是作者的一些注释代码,可以参考这个把注释写到你的代码相应的位置:
@api 定义API的请求方法、路径和名字
@apiDescription 定义API的描述
@apiGroup 定义API的分组
@apiParam 定义API的参数
@apiParamExample 参数请求的事例
@apiVersion 版本
@apiErrorExample API错误示例
@apiSuccessExample API正常示例

生成api文档

QQ图片20180525160616

执行命令apidoc -i src/ -o apidoc/

-i src/是把src文件夹下带有apidoc语法注释的代码全部生成文档
-o apidoc/是文档的生成目录
生成完成,打开apidoc文件夹下的index.html文件

生成案例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
/**
* @api {post} /login 用户登录
* @apiGroup Login
* @apiVersion 1.0.0
* @apiParam {String} username 用户名
* @apiParam {String} password 用户名密码
*
* @apiSuccess (200){Array} data 返回数据
* @apiSuccess (200){Int} status_code 状态码
* @apiSuccess (200){String} msg 返回消息
*
* @apiSuccessExample {json} 成功:
* {
* "data": {
* "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwOlwvXC93d3cuYXBpLmNvbVwvYXBpXC9sb2dpbiIsImlhdCI6MTUyNjI2ODkwMSwiZXhwIjoxNTI2MjcyNTAxLCJuYmYiOjE1MjYyNjg5MDEsImp0aSI6ImlnRXo5UG5Ta3d4b2wxc3YiLCJzdWIiOjEsInBydiI6ImM4MjkyMjM4MzVkMTExMzhmMDhhY2U1NmZmYTY2MjhiYzI2ODNjYjUifQ.AwF41Evq0p3fAFNV8Uw11zjHv6sOxBEWXKwtTwdnoXA" //登录凭证
* },
* "status": 200, //状态码
* "msg": "" //成功信息
* }
*
* @apiError (400){Int} status_code 状态码
* @apiError (400){String} msg 返回消息
*
* @apiErrorExample {json} 失败:
* {
* "msg": "用户名或者密码错误", //错误信息
* "status_code": 201, //状态码
* }
*/

QQ图片20180525155309-1024x591


发表评论

0 个回复

谁取了落叶

谁取了落叶

12 2018-09-02 加入 北京

(谁取了落叶)

近期更新文章