<<
>>

apidoc 生成api文档

张映 发表于 2017-02-18

分类目录： 技术其他

标签：, ,

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

1，安装nodejs

  1. # yum install nodejs npm  

2，安装apidoc

  1. # 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

查看复制打印?
  1. <?php  
  2.   
  3. class UserController{  
  4.   
  5.  /** 
  6.  * @api {POST} /api/user/getUserInfo 
  7.  * @apiName 取得用户信息 api 
  8.  * @apiGroup 用户组 
  9.  * @apiVersion 1.0.1 
  10.  * @apiDescription 取得用户信息 
  11.  * @apiPermission 登录用户 
  12.  * @apiSampleRequest http://api.test.com/api/user/getUserInfo 
  13.  * @apiParam {int} [id] any id 
  14.  * @apiParamExample {json} 请求例子: 
  15.  * { 
  16.  * "id": 4711 
  17.  * } 
  18.  * @apiSuccess (200) {String} msg 信息 
  19.  * @apiSuccess (200) {int} code 200 
  20.  * @apiSuccess (200) {String} name 真实姓名 
  21.  * @apiSuccess (200) {String} mobile 手机号 
  22.  * @apiSuccess (200) {String} birthday 生日 
  23.  * @apiSuccess (200) {String} email 邮箱 
  24.  * @apiSuccessExample {json} 返回样例: 
  25.  * { 
  26.  * "code": 200, 
  27.  * "msg": "", 
  28.  * "name": "真实姓名", 
  29.  * "mobile": 12345678901, 
  30.  * "birthday": "1980-03-05", 
  31.  * "email": "test@gamil.com" 
  32.  * } 
  33.  * @apiErrorExample {json} 错误返回: 
  34.  * { 
  35.  * "code": 14695 
  36.  * "msg": "数据出错" 
  37.  * } 
  38.  */  
  39.  public function getUserInfo(){  
  40.   
  41.  }  
  42. }  
  43.   
  44. ?>  

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

4，生成文档

在根目录mytest创建apidoc.json

查看复制打印?
  1. [root@localhost mytest]# cat apidoc.json  
  2. {  
  3.     "name": "我的测试",  
  4.     "version": "1.0.0",  
  5.     "description": "测试",  
  6.     "title": "测试",  
  7.     "url" : "https://api.test.com"  
  8. }  
  9.   
  10. # apidoc -i mytest/ -o ./doc  


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

相关文章

2 条评论

  1. sentangle 留言 (2017年3月2日 01:06 ):

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

  2. Dong 留言 (2017年11月27日 05:47 ):

    很多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