工具名称:APIDOC
Git地址:https://github.com/apidoc/apidoc
项目地址:http://apidocjs.com/
样例项目:http://apidocjs.com/example_basic/

APIDOC使用指南:https://www.jianshu.com/p/34eac66b47e3

全局安装

安装NodeJS后自动安装了npm管理工具,使用npm管理工具在cmd下安装apidoc

注意:Windows用户需在cmd下执行安装命令,不要在git bash下执行安装命令;如果安装过程中失败或安装到某一模块时停顿,则选择连接另外一个网络重试

  1. cd d:cd nodejsnpm install apidoc -g

编写注释

编写header.md

  1. ### 错误代码
  2.  
  3. 1. 返回成功的标识为 code,值为“200000”说明返回成功,值大于200000说明返回错误2. 返回的错误描述为 msg,值可能为空3. 返回的数据为 data,值可能为空
  4.  
  5. **示例代码**
  6.  
  7. 成功
  8.  
  9. { "code":200000, "msg":"操作成功", "data":"" }
  10.  
  11. 失败
  12.  
  13. { "code":200001, "msg":"参数不全", "data":"" }

编写错误码:例如:restapi/controllers/ResponseCode.php

  1. <?php
  2. /**
  3. *
  4. * User: qiaoweinqing
  5. * Date: 2018/5/30
  6. * Time: 19:51
  7. */
  8.  
  9. namespace restapi\controllers;
  10.  
  11. class ResponseCode
  12. {
  13. /**
  14. * @apiDefine ResponseCode 返回码
  15. */
  16.  
  17. /**
  18. * @apiDescription
  19. * 200000 执行成功
  20. *
  21. * 200010 缺少参数
  22. *
  23. * 200020 系统错误
  24. *
  25. * 201001 - 204000 标签模块
  26. * @api {常量} 类ResponseCode
  27. * @apiParam {200000} SUCESS_CODE 返回成功
  28. * @apiParam {200010} ERROR_CODE_MISS_PARAM 缺少参数
  29. *
  30. * @apiParam {201001} ERROR_CODE_TAG_NAME_IS_NULL 标签名称不能为空
  31. * @apiParam {201002} ERROR_CODE_PARENT_TAG_CODE_IS_NULL 父级标签编码不能为空
  32. * @apiParam {201003} ERROR_CODE_ATTRIBUTES_REQUIRED 参数必填
  33. * @apiParam {201004} ERROR_CODE_TAG_SAVE_FAILED 创建或修改标签失败
  34. * @apiParam {201005} ERROR_CODE_TAG_ID_IS_NULL 标签ID不能为空
  35. * @apiParam {201006} ERROR_CODE_TAG_ID_NOT_EXISTENT 标签不存在
  36. * @apiParam {201007} ERROR_CODE_TAG_DELETE_FAILED 删除标签失败
  37. * @apiParam {201008} ERROR_CODE_PERMISSION_DENY 无权限
  38. *
  39. * @apiGroup ResponseCode
  40. */
  41. public function responserCode(){
  42.  
  43. }
  44.  
  45. const SUCESS_CODE=200000;
  46.  
  47. const ERROR_CODE_MISS_PARAM=200010;
  48.  
  49. // 标签
  50. const ERROR_CODE_TAG_NAME_IS_NULL = 201001;
  51. const ERROR_CODE_PARENT_TAG_CODE_IS_NULL = 201002;
  52. const ERROR_CODE_ATTRIBUTES_REQUIRED = 201003;
  53. const ERROR_CODE_TAG_SAVE_FAILED = 201004;
  54. const ERROR_CODE_TAG_ID_IS_NULL = 201005;
  55. const ERROR_CODE_TAG_ID_NOT_EXISTENT = 201006;
  56. const ERROR_CODE_TAG_DELETE_FAILED = 201007;
  57. const ERROR_CODE_PERMISSION_DENY = 201008;
  58.  
  59. }

编写API:例如:restapi/controllers/TagController.php

  1. <?php
  2. /**
  3. * 道强
  4. */
  5. namespace restapi\controllers;
  6.  
  7. use core\models\Tag;
  8. use Yii;
  9. use restapi\controllers\CommonController;
  10. use restapi\controllers\ResponseCode;
  11. use service\tag\TagService;
  12.  
  13. class TagController extends CommonController
  14. {
  15. public $enableCsrfValidation = false;
  16.  
  17. /**
  18. * @apiDefine TagController 标签管理
  19. * 标签编码规则:使用创建当天的6位年月日加上当天的标签生成6位顺序数;例如:2019年04月19日生成的第二个标签,编码为"190419000002"
  20. */
  21.  
  22. /**
  23. * @api {post} /tag/create-or-update-children 创建或更新子标签
  24. * @apiName actionCreateOrUpdateChildren
  25. * @apiGroup TagController
  26. * @apiDescription 在指定标签下创建或更新多个字标签的信息,主要包括更新字标签的名称和标签的类型
  27. *
  28. * @apiParam {String} platform 平台唯一标识
  29. * @apiParam {String} [user] 用户唯一标识
  30. * @apiParam {String} parent_tag_code 父级标签编码
  31. * @apiParam {Array} children 字标签信息列表
  32. * @apiParam {String} children.tag_name 子标签名称
  33. * @apiParam {String} children.tag_code 子标签编码
  34. * @apiParam {Number} children.tag_type 子标签类型
  35. * @apiParamExample {json} 请求示例
  36. * {
  37. * "platform": "yaogonghui",
  38. * "user": "",
  39. * "parent_tag_code": "190419000001",
  40. * "children": [
  41. * {
  42. * "tag_name": "规格",
  43. * "tag_code": "190419000002",
  44. * "tag_type": 1,
  45. * },
  46. * {
  47. * "tag_name": "产地",
  48. * "tag_code": "190419000003",
  49. * "tag_type": 1,
  50. * }],
  51. * }
  52. * @apiSuccess {Number} success_num 创建或更新子标签成功条数
  53. * @apiSuccess {Array} children 子标签信息列表
  54. * @apiSuccess {Number} children.id 子标签ID
  55. * @apiSuccess {String} children.platform 子标签所属平台
  56. * @apiSuccess {String} children.user 子标签所属用户
  57. * @apiSuccess {String} children.tag_name 子标签名称
  58. * @apiSuccess {String} children.tag_code 子标签编码
  59. * @apiSuccess {Number} children.tag_type 子标签类型
  60. * @apiSuccess {String} children.tag_icon 子标签图标
  61. * @apiSuccess {Number} children.tag_sequence 子标签显示顺序
  62. * @apiSuccess {String} children.tag_remark 子标签备注说明
  63. * @apiSuccess {Number} children.created_at 子标签创建时间戳
  64. * @apiSuccess {Number} children.updated_at 子标签更新时间戳
  65. * @apiSuccess {Number} children.is_del 子标签是否软删除
  66. *
  67. * @apiSuccessExample 返回示例
  68. * {
  69. * "code": 200000,
  70. * "ret": {
  71. * "success_num": 2,
  72. * "children": [
  73. * {
  74. * "id": "2",
  75. * "platform": "",
  76. * "user": "",
  77. * "tag_name": "规格",
  78. * "tag_code": "190419000002",
  79. * "tag_type": 1,
  80. * "tag_icon": "",
  81. * "tag_sequence": 1,
  82. * "tag_remark": "",
  83. * "created_at": 1555593200,
  84. * "updated_at": 1555593200,
  85. * "is_del": 0,
  86. * },
  87. * {
  88. * "id": "3",
  89. * "platform": "",
  90. * "user": "",
  91. * "tag_name": "产地",
  92. * "tag_code": "190419000003",
  93. * "tag_type": 1,
  94. * "tag_icon": "",
  95. * "tag_sequence": 2,
  96. * "tag_remark": "",
  97. * "created_at": 1555593200,
  98. * "updated_at": 1555593200,
  99. * "is_del": 0,
  100. * }]
  101. * },
  102. * "alertMsg": "创建或更新子标签成功!"
  103. * }
  104. *
  105. * @apiError 201004 创建或修改标签失败
  106. * @apiError 200010 缺少参数
  107. * @apiError 201001 标签名称不能为空
  108. * @apiError 201002 父级标签编码不能为空
  109. */
  110. public function actionCreateOrUpdateChildren()
  111. {
  112. $params = Yii::$app->request->post();
  113. $result = TagService::createOrUpdateChildren($params);
  114. return $this->responseData($result['data'], $result['code'], $result['msg']);
  115. }
  116.  
  117. /**
  118. * @api {post} /tag/update 修改标签
  119. * @apiName actionUpdate
  120. * @apiGroup TagController
  121. * @apiDescription 修改标签的所属父级、名称
  122. *
  123. * @apiParam {String} platform 平台唯一标识
  124. * @apiParam {String} [user] 用户唯一标识
  125. * @apiParam {String} tag_code 标签编码
  126. * @apiParam {String} parent_tag_code 父级标签编码
  127. * @apiParam {String} tag_name 标签名称
  128. * @apiParamExample {json} 请求示例
  129. * {
  130. * "platform": "yaogonghui",
  131. * "user": "18519654001",
  132. * "tag_code": "190419000002",
  133. * "parent_tag_code": "190419000001",
  134. * "tag_name": "规格",
  135. * }
  136. * @apiSuccess {Number} success_num 成功条数
  137. * @apiSuccess {String} tag_code 标签编码
  138. * @apiSuccess {String} parent_tag_code 父级标签编码
  139. * @apiSuccess {String} tag_name 标签名称
  140. * @apiSuccessExample 返回示例
  141. * {
  142. * "code": 200000,
  143. * "ret": {
  144. * "success_num": 1,
  145. * "tag_code": "190419000002",
  146. * "parent_tag_code": "190419000001",
  147. * "tag_name": "规格",
  148. * },
  149. * "alertMsg": "修改标签信息成功!"
  150. * }
  151. * @apiError 201004 创建或修改标签失败
  152. * @apiError 200010 缺少参数
  153. * @apiError 201001 标签名称不能为空
  154. * @apiError 201002 父级标签编码不能为空
  155. */
  156. public function actionUpdate()
  157. {
  158. // var_dump(Yii::$app->request->get());
  159. // var_dump(Yii::$app->request->post());
  160. // var_dump(Yii::$app->request->bodyParam);
  161. // var_dump(json_decode(Yii::$app->request->getRawBody(), true));
  162. $params = Yii::$app->request->post();
  163.  
  164. $result = TagService::update($params);
  165.  
  166. return $this->responseData($result['data'], $result['code'], $result['msg']);
  167.  
  168. }
  169.  
  170. /**
  171. * @api {post} /tag/delete 删除标签及其所有子标签
  172. * @apiName actionDelete
  173. * @apiGroup TagController
  174. *
  175. * @apiParam {String} platform 平台唯一标识
  176. * @apiParam {String} [user] 用户唯一标识
  177. * @apiParam {String} tag_code 标签编码
  178. * @apiParamExample {json} 请求示例
  179. * {
  180. * "platform": "yaogonghui",
  181. * "user": "",
  182. * "tag_code": "190419000001",
  183. * }
  184. * @apiSuccess {Number} success_num 成功条数
  185. * @apiSuccessExample 返回示例
  186. * {
  187. * "code": 200000,
  188. * "ret": {"success_num": 3},
  189. * "alertMsg": "删除标签及其字标签成功!"
  190. * }
  191. *
  192. * @apiError 201007 删除标签失败
  193. */
  194. public function actionDelete()
  195. {
  196. $params = Yii::$app->request->post();
  197. $result = TagService::delete($params);
  198. return $this->responseData($result['data'], $result['code'], $result['msg']);
  199. }
  200.  
  201. /**
  202. * @api {post} /tag/update-sequence 标签移位
  203. * @apiName actionUpdateSequence
  204. * @apiGroup TagController
  205. * @apiDescription 将标签移动至参照物标签的后面
  206. *
  207. * @apiParam {String} platform 平台唯一标识
  208. * @apiParam {String} [user] 用户唯一标识
  209. * @apiParam {String} tag_code 标签编码
  210. * @apiParam {String} dest_tag_code 参照物标签的编码
  211. * @apiParamExample {json} 请求示例
  212. * {
  213. * "platform": "yaogonghui",
  214. * "user": "",
  215. * "tag_code": "190419000002",
  216. * "dest_tag_code": "190419000003",
  217. * }
  218. * @apiSuccess {Number} success_num 影响的标签记录数
  219. * @apiSuccessExample 返回示例
  220. * {
  221. * "code": 200000,
  222. * "ret": {"success_num": 5},
  223. * "alertMsg": "标签移位成功!"
  224. * }
  225. *
  226. * @apiError 201004 创建或修改标签失败
  227. */
  228. public function actionUpdateSequence()
  229. {
  230. $params = Yii::$app->request->post();
  231. $result = TagService::updateSequence($params);
  232. return $this->responseData($result['data'], $result['code'], $result['msg']);
  233. }
  234.  
  235. /**
  236. * @api {get} /tag/list-tree 标签树列表
  237. * @apiName actionListTree
  238. * @apiGroup TagController
  239. *
  240. * @apiParam {String} platform 平台唯一标识
  241. * @apiParam {String} [user] 用户唯一标识
  242. * @apiParam {String} [tag_code_path] 标签编码从父级至子级使用文件目录分隔符"/"拼接
  243. * @apiParam {String} [deep=0] 从叶子标签开始计算的深度,0代表无限级深度
  244. * @apiParamExample {json} 请求示例
  245. * {
  246. * "platform": "yaogonghui",
  247. * "user": "18519654001",
  248. * "tag_code_path": "190419000001/190419000002",
  249. * "deep": 1
  250. * }
  251. *
  252. * @apiSuccess {Array} list 标签列表
  253. * @apiSuccess {Number} list.id 标签ID
  254. * @apiSuccess {String} list.platform 标签所属平台
  255. * @apiSuccess {String} list.user 标签所属用户
  256. * @apiSuccess {String} list.tag_name 标签名称
  257. * @apiSuccess {String} list.tag_code 标签编码
  258. * @apiSuccess {Number} list.tag_type 标签类型
  259. * @apiSuccess {String} list.tag_icon 标签图标
  260. * @apiSuccess {Number} list.tag_sequence 标签显示顺序
  261. * @apiSuccess {String} list.tag_remark 标签备注说明
  262. * @apiSuccess {Number} list.created_at 标签创建时间戳
  263. * @apiSuccess {Number} list.updated_at 标签更新时间戳
  264. * @apiSuccess {Number} list.is_del 标签是否软删除
  265. * @apiSuccess {Array} list.children 字标签列表
  266. * @apiSuccess {Array} pagination 分页信息
  267. * @apiSuccess {Number} pagination.total 总条数
  268. * @apiSuccess {Number} pagination.pageSize 每页条数
  269. * @apiSuccess {Number} pagination.current 当前页
  270. * @apiSuccessExample 返回示例
  271. *
  272. * {
  273. * "code": 200000,
  274. * "ret": {
  275. * "id": "1",
  276. * "platform": "",
  277. * "user": "",
  278. * "tag_name": "白芍",
  279. * "tag_code": "190419000001",
  280. * "tag_type": 1,
  281. * "tag_icon": "",
  282. * "tag_sequence": 1,
  283. * "tag_remark": "",
  284. * "created_at": 1555593200,
  285. * "updated_at": 1555593200,
  286. * "is_del": 0,
  287. * "children": [
  288. * {
  289. * "id": "2",
  290. * "platform": "",
  291. * "user": "",
  292. * "tag_name": "规格",
  293. * "tag_code": "190419000002",
  294. * "tag_type": 1,
  295. * "tag_icon": "",
  296. * "tag_sequence": 1,
  297. * "tag_remark": "",
  298. * "created_at": 1555593200,
  299. * "updated_at": 1555593200,
  300. * "is_del": 0,
  301. * "children": [
  302. * {
  303. * "id": "4",
  304. * "platform": "",
  305. * "user": "",
  306. * "tag_name": "统货",
  307. * "tag_code": "190419000004",
  308. * "tag_type": 1,
  309. * "tag_icon": "",
  310. * "tag_sequence": 1,
  311. * "tag_remark": "",
  312. * "created_at": 1555593200,
  313. * "updated_at": 1555593200,
  314. * "is_del": 0,
  315. * }]
  316. * }]
  317. * "pagination": {
  318. * "total": 3,
  319. * "pageSize": 20,
  320. * "current": 1
  321. * }
  322. * },
  323. * "alertMsg": "标签列表查询成功"
  324. * }
  325. * @apiError 201006 标签不存在
  326. */
  327. public function actionListTree()
  328. {
  329. $params = Yii::$app->request->post();
  330.  
  331. // $params['tag_code_path'] = '190419000001';
  332. // $params['deep'] = 2;
  333.  
  334. if (!isset($params['user'])){
  335. $params['user'] = '';
  336. }
  337. if (!isset($params['tag_code_path'])){
  338. $params['tag_code_path'] = '';
  339. }
  340. if (!isset($params['deep'])){
  341. $params['deep'] = 0;
  342. }
  343. $result = TagService::listTree($params);
  344. // echo '<pre>';
  345. // print_r($result);
  346. // echo '</pre>';
  347. // die;
  348. return $this->responseData($result['data'], $result['code'], $result['msg']);
  349. }
  350. }

生成API文档

  1. cd f:
  2. cd project/chgg-user-service-api
  3. cd restapi

  apidoc -i restapi/controllers/ -c restapi/web/ -o restapi/web/apidoc

  1.  

解释:

  1. # APIDOC的使用命令api/controllers指的是RestAPI代码目录api/web指的是RestAPI的入口脚本index.php的目录api/web/apidoc指的是API文档的存放目录

apidoc -i restapi/controllers/ -c restapi/web/ -o restapi/web/apidoc

可封装未sh脚本

  1. ./genapidoc.sh
  2.  
  3. #具体内容为

apidoc -i restapi/controllers/ -c restapi/web/ -o restapi/web/apidoc

  1.  

实例文档地址:

  1. http://tagdoc.test.chinahanguang.com/index.html

生成结果

更多示例

  1. /**
  2. * @apiDefine TestController 测试管理
  3. */
  4.  
  5. /**
  6. *
  7. * @apiDeprecated 现在请使用(#Test:_test)
  8. * @api {post} /tag/test 01-测试
  9. * @apiGroup TestController
  10. * @apiName actionTest
  11. * @apiVersion 1.6.2
  12. * @apiPermission 无
  13. * @apiExample {curl} 使用curl
  14. * curl -i http://localhost/tag/test
  15. *
  16. * @apiHeader {String} access_token 授权令牌
  17. * @apiHeaderExample {json} 请求头示例
  18. * {
  19. * "access_token": "abcdddd78789a7t89e8t9t9ew8t7e89t89te"
  20. * }
  21. * @apiParam {String} [firstname] Optional 姓
  22. * @apiParam {String} lastname Mandatory 名
  23. * @apiParam {String} country="中国" Mandatory 国籍
  24. * @apiParam {Number} [age=18] Optional 年龄
  25. * @apiParam (Login) {String} pass 登录密码
  26. * @apiParamExample {json} 请求示例
  27. * {
  28. * "content": "This is an example content"
  29. * }
  30. * @apiSuccess {String} firstname 姓
  31. * @apiSuccessExample 返回示例
  32. * {
  33. * "code": 200000,
  34. * "ret": {
  35. * "id": 1,
  36. * "pid": "0",
  37. * "tag_name": "药材"
  38. * "tag_code": "0011"
  39. * },
  40. * "alertMsg": "创建标签成功!"
  41. * }
  42. * @apiSampleRequest http://www.example.com
  43. * @apiError 10001 缺少参数
  44. * @apiErrorExample {json} 错误示例
  45. * HTTP/1.1 404 Not Found
  46. * {
  47. * "error": "未找到用户"
  48. * }
  49. */
  50. public function actionTest()
  51. {
  52.  
  53. }

APIDOC的使用的更多相关文章

  1. apidoc

    1.安装node http://nodejs.cn/download/ 下载二进制包,解压,配置环境 export NODE_HOME=/usr/local/nodeexport PATH=$NODE ...

  2. 基于php开发的RESTful ApiDoc文档

    apiDoc基于rest的web API文档生成器,可以根据代码注释生成web api文档,自动生成静态的html网页文档,不仅支持项目版本号,还支持API版本号. 使用apiDoc不需要自己麻烦的调 ...

  3. ApiDoc 文档使用方式

    1.安装node.js 2.打开node.js 命令窗(shell)键入npm install apidoc -g 自动安装(几分钟) 3. C:\Users\user\AppData\Roaming ...

  4. apidoc,一个相当不错的文档生成器

    http://apidocjs.com/ 例子:myapp目录下的MyCode.java /** * * @api {get} /company/list 获取公司信息 * @apiName 获取公司 ...

  5. webApi文档好帮手-apidoc使用教程

    来源:http://blog.csdn.net/xumin198908/article/details/41964159 在开发后台接口的过程中,我们肯定要提供一份api接口文档给终端app. 目前大 ...

  6. 使用apidoc根据JS文件生成接口文档

    1.安装nodejs.下载网址:http://www.nodejs.org: 2.安装apidoc.运行cmd,切换到nodejs的安装目录,在命令行输入: 1 npm install apidoc ...

  7. 关于apidoc文档生成不了的一个原因

    前几天在写完API后,写注释文档,然后很习惯的去用apidoc取生成注释文档,但是奇怪的事发生了,没有注释的内容,也没有报错:注释代码如下: /* * @api {get} /applet/:id 根 ...

  8. apidoc快速生成在线文档,apidoc生成静态文件的生成规则以及原理分析

    在老大的指引下,需要将系统的json文件格式转换成apidoc的json格式,也就是json格式的重组,但是这个apidoc的生成格式是不固定的,因为apidoc有自己一套的生成规则,我需要研究一下是 ...

  9. Node与apidoc的邂逅——NodeJS Restful 的API文档生成

    作为后台根据需求文档开发完成接口后,交付给前台(angular vue等)做开发,不可能让前台每个接口调用都去查看你的后台代码一点点查找.前台开发若不懂你的代码呢?让他一个接口一个接口去问你怎么调用, ...

  10. 接口文档神器之apidoc

    //@desn:apidoc linux环境  windows环境使用 //@desn:码字不宜,转载请注明出处 //@author:张慧源  <turing_zhy@163.com> / ...

随机推荐

  1. 【css】常用css

    常用css--------下三角 常用css--------闪动效果 css #shandongFlash { width:100px; height:100px; background:#f8b55 ...

  2. Linux 分卷压缩

    例如,要将大文件夹 PYNQ 分卷压缩成 1G 的单元大小,如下命令(类似的可以指定 tar 的参数为 czf 而生产 .tar.gz 格式的压缩包:可以指定分卷大小例如 500M 等),压缩完成后, ...

  3. leetcode 74. Search a 2D Matrix 、240. Search a 2D Matrix II

    74. Search a 2D Matrix 整个二维数组是有序排列的,可以把这个想象成一个有序的一维数组,然后用二分找中间值就好了. 这个时候需要将全部的长度转换为相应的坐标,/col获得x坐标,% ...

  4. 最长上升子序列(LIS)

    (我先扯些没用的) 我这个笨孩子 学点东西好慢好慢的 我还贪玩 于是 将自己陷入了一个超级超级超级差的境地 可 我还傻乎乎的保有着天真的梦想(理想?) 所以现在我要加倍的努力努力再努力了 只能嘎油了 ...

  5. 1-STM32带你入坑系列(STM32介绍)

    由于自己的物联网开发板上的单片机是用的STM32,但是有些朋友没有用过,所以我将用这块开发板,带着大家入门STM32 先介绍一下STM32,我是在大三下学期的时候开始接触STM32,当时是想做一个小车 ...

  6. CISCO交换机-SNMP配置

    1.1     SNMP基础配置 router> enable 进入路由器是用户模式 router# conf terminal 进入路由器的全局配置模式 #snmp-server commun ...

  7. 牛客网 Python 编程输入规范

    import sys try: while True: line = sys.stdin.readline().strip() if line == '': break lines = line.sp ...

  8. Python-time模块-58

    time 模块: Eva_J import time time.sleep(100) #时间睡眠 print(time.time()) #返回一个以秒为单位的时间 时间模块 和时间有关系的我们就要用到 ...

  9. java 接口实现防盗门功能

    Door: package locker; public abstract class Door { public abstract void open(); public abstract void ...

  10. 出题人的RP值(牛客练习赛38--A题)(排序)

    链接:https://ac.nowcoder.com/acm/contest/358/A来源:牛客网 题目描述 众所周知,每个人都有自己的rp值(是个非负实数),膜别人可以从别人身上吸取rp值. 然而 ...