apidoc 生成api文档

张映 发表于 2017-02-18

分类目录: 技术其他

标签:, ,

接口太多,管理文档是件麻烦事。apidoc可以帮我们解决这个问题。根据apidoc的格式写注释,还可以提高了代码的可读性。推荐使用。

1,安装nodejs

# yum install nodejs npm

2,安装apidoc

# npm install apidoc@0.12 -g

centos 6.5 64位装了,0.17.5后,生成文档时,总是报error: Object /var/www/mytest/user.php has no method 'startsWith'

3,测试php

<?php

class UserController{

 /**
 * @api {POST} /api/user/getUserInfo
 * @apiName 取得用户信息 api
 * @apiGroup 用户组
 * @apiVersion 1.0.1
 * @apiDescription 取得用户信息
 * @apiPermission 登录用户
 * @apiSampleRequest http://api.test.com/api/user/getUserInfo
 * @apiParam {int} [id] any id
 * @apiParamExample {json} 请求例子:
 * {
 * "id": 4711
 * }
 * @apiSuccess (200) {String} msg 信息
 * @apiSuccess (200) {int} code 200
 * @apiSuccess (200) {String} name 真实姓名
 * @apiSuccess (200) {String} mobile 手机号
 * @apiSuccess (200) {String} birthday 生日
 * @apiSuccess (200) {String} email 邮箱
 * @apiSuccessExample {json} 返回样例:
 * {
 * "code": 200,
 * "msg": "",
 * "name": "真实姓名",
 * "mobile": 12345678901,
 * "birthday": "1980-03-05",
 * "email": "test@gamil.com"
 * }
 * @apiErrorExample {json} 错误返回:
 * {
 * "code": 14695
 * "msg": "数据出错"
 * }
 */
 public function getUserInfo(){

 }
}

?>

具体格式,参数官方网站,http://apidocjs.com/

4,生成文档

在根目录mytest创建apidoc.json

[root@localhost mytest]# cat apidoc.json
{
	"name": "我的测试",
	"version": "1.0.0",
	"description": "测试",
	"title": "测试",
	"url" : "https://api.test.com"
}

# apidoc -i mytest/ -o ./doc


转载请注明
作者:海底苍鹰
地址:http://blog.51yip.com/other/1847.html/comment-page-1

2 条评论

  1. sentangle 留言

    linux命令手册的网站
    建议关闭百度的划词分享
    不能复制命令很不方便

  2. Dong 留言

    很多API doc生成工具生成doc需要重度依赖代码里加注解的方式,并且不支持自动化测试RESTful API。

    之前习惯用一款名字为 WisdomTool REST Client,它能够基于测试过的历史记录自动生成精美的RESTful API文档,完全不用在代码里加注解,支持自动化测试RESTful API,输出精美的测试报告。
    轻量级的工具,功能却很精悍哦!

    https://github.com/wisdomtool/rest-client

    Most of API doc tools do not support automated testing.

    Once used a tool called WisdomTool REST Client supports automatically generating exquisite RESTful API documentation based on history testing cases without adding annotations to the code, it also supports automated testing, and outputs exquisite report.

    Lightweight tool with very powerful features!

    https://github.com/wisdomtool/rest-client

留下评论

留下评论
  • (必需)
  • (必需) (will not be published)
  • (必需)   7X4=?