APIDOC的使用
工具名称: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下执行安装命令;如果安装过程中失败或安装到某一模块时停顿,则选择连接另外一个网络重试
- cd d:cd nodejsnpm install apidoc -g
编写注释
编写header.md
- ### 错误代码
- 1. 返回成功的标识为 code,值为“200000”说明返回成功,值大于200000说明返回错误2. 返回的错误描述为 msg,值可能为空3. 返回的数据为 data,值可能为空
- **示例代码**
- 成功
- { "code":200000, "msg":"操作成功", "data":"" }
- 失败
- { "code":200001, "msg":"参数不全", "data":"" }
编写错误码:例如:restapi/controllers/ResponseCode.php
- <?php
- /**
- *
- * User: qiaoweinqing
- * Date: 2018/5/30
- * Time: 19:51
- */
- namespace restapi\controllers;
- class ResponseCode
- {
- /**
- * @apiDefine ResponseCode 返回码
- */
- /**
- * @apiDescription
- * 200000 执行成功
- *
- * 200010 缺少参数
- *
- * 200020 系统错误
- *
- * 201001 - 204000 标签模块
- * @api {常量} 类ResponseCode
- * @apiParam {200000} SUCESS_CODE 返回成功
- * @apiParam {200010} ERROR_CODE_MISS_PARAM 缺少参数
- *
- * @apiParam {201001} ERROR_CODE_TAG_NAME_IS_NULL 标签名称不能为空
- * @apiParam {201002} ERROR_CODE_PARENT_TAG_CODE_IS_NULL 父级标签编码不能为空
- * @apiParam {201003} ERROR_CODE_ATTRIBUTES_REQUIRED 参数必填
- * @apiParam {201004} ERROR_CODE_TAG_SAVE_FAILED 创建或修改标签失败
- * @apiParam {201005} ERROR_CODE_TAG_ID_IS_NULL 标签ID不能为空
- * @apiParam {201006} ERROR_CODE_TAG_ID_NOT_EXISTENT 标签不存在
- * @apiParam {201007} ERROR_CODE_TAG_DELETE_FAILED 删除标签失败
- * @apiParam {201008} ERROR_CODE_PERMISSION_DENY 无权限
- *
- * @apiGroup ResponseCode
- */
- public function responserCode(){
- }
- const SUCESS_CODE=200000;
- const ERROR_CODE_MISS_PARAM=200010;
- // 标签
- const ERROR_CODE_TAG_NAME_IS_NULL = 201001;
- const ERROR_CODE_PARENT_TAG_CODE_IS_NULL = 201002;
- const ERROR_CODE_ATTRIBUTES_REQUIRED = 201003;
- const ERROR_CODE_TAG_SAVE_FAILED = 201004;
- const ERROR_CODE_TAG_ID_IS_NULL = 201005;
- const ERROR_CODE_TAG_ID_NOT_EXISTENT = 201006;
- const ERROR_CODE_TAG_DELETE_FAILED = 201007;
- const ERROR_CODE_PERMISSION_DENY = 201008;
- }
编写API:例如:restapi/controllers/TagController.php
- <?php
- /**
- * 道强
- */
- namespace restapi\controllers;
- use core\models\Tag;
- use Yii;
- use restapi\controllers\CommonController;
- use restapi\controllers\ResponseCode;
- use service\tag\TagService;
- class TagController extends CommonController
- {
- public $enableCsrfValidation = false;
- /**
- * @apiDefine TagController 标签管理
- * 标签编码规则:使用创建当天的6位年月日加上当天的标签生成6位顺序数;例如:2019年04月19日生成的第二个标签,编码为"190419000002"
- */
- /**
- * @api {post} /tag/create-or-update-children 创建或更新子标签
- * @apiName actionCreateOrUpdateChildren
- * @apiGroup TagController
- * @apiDescription 在指定标签下创建或更新多个字标签的信息,主要包括更新字标签的名称和标签的类型
- *
- * @apiParam {String} platform 平台唯一标识
- * @apiParam {String} [user] 用户唯一标识
- * @apiParam {String} parent_tag_code 父级标签编码
- * @apiParam {Array} children 字标签信息列表
- * @apiParam {String} children.tag_name 子标签名称
- * @apiParam {String} children.tag_code 子标签编码
- * @apiParam {Number} children.tag_type 子标签类型
- * @apiParamExample {json} 请求示例
- * {
- * "platform": "yaogonghui",
- * "user": "",
- * "parent_tag_code": "190419000001",
- * "children": [
- * {
- * "tag_name": "规格",
- * "tag_code": "190419000002",
- * "tag_type": 1,
- * },
- * {
- * "tag_name": "产地",
- * "tag_code": "190419000003",
- * "tag_type": 1,
- * }],
- * }
- * @apiSuccess {Number} success_num 创建或更新子标签成功条数
- * @apiSuccess {Array} children 子标签信息列表
- * @apiSuccess {Number} children.id 子标签ID
- * @apiSuccess {String} children.platform 子标签所属平台
- * @apiSuccess {String} children.user 子标签所属用户
- * @apiSuccess {String} children.tag_name 子标签名称
- * @apiSuccess {String} children.tag_code 子标签编码
- * @apiSuccess {Number} children.tag_type 子标签类型
- * @apiSuccess {String} children.tag_icon 子标签图标
- * @apiSuccess {Number} children.tag_sequence 子标签显示顺序
- * @apiSuccess {String} children.tag_remark 子标签备注说明
- * @apiSuccess {Number} children.created_at 子标签创建时间戳
- * @apiSuccess {Number} children.updated_at 子标签更新时间戳
- * @apiSuccess {Number} children.is_del 子标签是否软删除
- *
- * @apiSuccessExample 返回示例
- * {
- * "code": 200000,
- * "ret": {
- * "success_num": 2,
- * "children": [
- * {
- * "id": "2",
- * "platform": "",
- * "user": "",
- * "tag_name": "规格",
- * "tag_code": "190419000002",
- * "tag_type": 1,
- * "tag_icon": "",
- * "tag_sequence": 1,
- * "tag_remark": "",
- * "created_at": 1555593200,
- * "updated_at": 1555593200,
- * "is_del": 0,
- * },
- * {
- * "id": "3",
- * "platform": "",
- * "user": "",
- * "tag_name": "产地",
- * "tag_code": "190419000003",
- * "tag_type": 1,
- * "tag_icon": "",
- * "tag_sequence": 2,
- * "tag_remark": "",
- * "created_at": 1555593200,
- * "updated_at": 1555593200,
- * "is_del": 0,
- * }]
- * },
- * "alertMsg": "创建或更新子标签成功!"
- * }
- *
- * @apiError 201004 创建或修改标签失败
- * @apiError 200010 缺少参数
- * @apiError 201001 标签名称不能为空
- * @apiError 201002 父级标签编码不能为空
- */
- public function actionCreateOrUpdateChildren()
- {
- $params = Yii::$app->request->post();
- $result = TagService::createOrUpdateChildren($params);
- return $this->responseData($result['data'], $result['code'], $result['msg']);
- }
- /**
- * @api {post} /tag/update 修改标签
- * @apiName actionUpdate
- * @apiGroup TagController
- * @apiDescription 修改标签的所属父级、名称
- *
- * @apiParam {String} platform 平台唯一标识
- * @apiParam {String} [user] 用户唯一标识
- * @apiParam {String} tag_code 标签编码
- * @apiParam {String} parent_tag_code 父级标签编码
- * @apiParam {String} tag_name 标签名称
- * @apiParamExample {json} 请求示例
- * {
- * "platform": "yaogonghui",
- * "user": "18519654001",
- * "tag_code": "190419000002",
- * "parent_tag_code": "190419000001",
- * "tag_name": "规格",
- * }
- * @apiSuccess {Number} success_num 成功条数
- * @apiSuccess {String} tag_code 标签编码
- * @apiSuccess {String} parent_tag_code 父级标签编码
- * @apiSuccess {String} tag_name 标签名称
- * @apiSuccessExample 返回示例
- * {
- * "code": 200000,
- * "ret": {
- * "success_num": 1,
- * "tag_code": "190419000002",
- * "parent_tag_code": "190419000001",
- * "tag_name": "规格",
- * },
- * "alertMsg": "修改标签信息成功!"
- * }
- * @apiError 201004 创建或修改标签失败
- * @apiError 200010 缺少参数
- * @apiError 201001 标签名称不能为空
- * @apiError 201002 父级标签编码不能为空
- */
- public function actionUpdate()
- {
- // var_dump(Yii::$app->request->get());
- // var_dump(Yii::$app->request->post());
- // var_dump(Yii::$app->request->bodyParam);
- // var_dump(json_decode(Yii::$app->request->getRawBody(), true));
- $params = Yii::$app->request->post();
- $result = TagService::update($params);
- return $this->responseData($result['data'], $result['code'], $result['msg']);
- }
- /**
- * @api {post} /tag/delete 删除标签及其所有子标签
- * @apiName actionDelete
- * @apiGroup TagController
- *
- * @apiParam {String} platform 平台唯一标识
- * @apiParam {String} [user] 用户唯一标识
- * @apiParam {String} tag_code 标签编码
- * @apiParamExample {json} 请求示例
- * {
- * "platform": "yaogonghui",
- * "user": "",
- * "tag_code": "190419000001",
- * }
- * @apiSuccess {Number} success_num 成功条数
- * @apiSuccessExample 返回示例
- * {
- * "code": 200000,
- * "ret": {"success_num": 3},
- * "alertMsg": "删除标签及其字标签成功!"
- * }
- *
- * @apiError 201007 删除标签失败
- */
- public function actionDelete()
- {
- $params = Yii::$app->request->post();
- $result = TagService::delete($params);
- return $this->responseData($result['data'], $result['code'], $result['msg']);
- }
- /**
- * @api {post} /tag/update-sequence 标签移位
- * @apiName actionUpdateSequence
- * @apiGroup TagController
- * @apiDescription 将标签移动至参照物标签的后面
- *
- * @apiParam {String} platform 平台唯一标识
- * @apiParam {String} [user] 用户唯一标识
- * @apiParam {String} tag_code 标签编码
- * @apiParam {String} dest_tag_code 参照物标签的编码
- * @apiParamExample {json} 请求示例
- * {
- * "platform": "yaogonghui",
- * "user": "",
- * "tag_code": "190419000002",
- * "dest_tag_code": "190419000003",
- * }
- * @apiSuccess {Number} success_num 影响的标签记录数
- * @apiSuccessExample 返回示例
- * {
- * "code": 200000,
- * "ret": {"success_num": 5},
- * "alertMsg": "标签移位成功!"
- * }
- *
- * @apiError 201004 创建或修改标签失败
- */
- public function actionUpdateSequence()
- {
- $params = Yii::$app->request->post();
- $result = TagService::updateSequence($params);
- return $this->responseData($result['data'], $result['code'], $result['msg']);
- }
- /**
- * @api {get} /tag/list-tree 标签树列表
- * @apiName actionListTree
- * @apiGroup TagController
- *
- * @apiParam {String} platform 平台唯一标识
- * @apiParam {String} [user] 用户唯一标识
- * @apiParam {String} [tag_code_path] 标签编码从父级至子级使用文件目录分隔符"/"拼接
- * @apiParam {String} [deep=0] 从叶子标签开始计算的深度,0代表无限级深度
- * @apiParamExample {json} 请求示例
- * {
- * "platform": "yaogonghui",
- * "user": "18519654001",
- * "tag_code_path": "190419000001/190419000002",
- * "deep": 1
- * }
- *
- * @apiSuccess {Array} list 标签列表
- * @apiSuccess {Number} list.id 标签ID
- * @apiSuccess {String} list.platform 标签所属平台
- * @apiSuccess {String} list.user 标签所属用户
- * @apiSuccess {String} list.tag_name 标签名称
- * @apiSuccess {String} list.tag_code 标签编码
- * @apiSuccess {Number} list.tag_type 标签类型
- * @apiSuccess {String} list.tag_icon 标签图标
- * @apiSuccess {Number} list.tag_sequence 标签显示顺序
- * @apiSuccess {String} list.tag_remark 标签备注说明
- * @apiSuccess {Number} list.created_at 标签创建时间戳
- * @apiSuccess {Number} list.updated_at 标签更新时间戳
- * @apiSuccess {Number} list.is_del 标签是否软删除
- * @apiSuccess {Array} list.children 字标签列表
- * @apiSuccess {Array} pagination 分页信息
- * @apiSuccess {Number} pagination.total 总条数
- * @apiSuccess {Number} pagination.pageSize 每页条数
- * @apiSuccess {Number} pagination.current 当前页
- * @apiSuccessExample 返回示例
- *
- * {
- * "code": 200000,
- * "ret": {
- * "id": "1",
- * "platform": "",
- * "user": "",
- * "tag_name": "白芍",
- * "tag_code": "190419000001",
- * "tag_type": 1,
- * "tag_icon": "",
- * "tag_sequence": 1,
- * "tag_remark": "",
- * "created_at": 1555593200,
- * "updated_at": 1555593200,
- * "is_del": 0,
- * "children": [
- * {
- * "id": "2",
- * "platform": "",
- * "user": "",
- * "tag_name": "规格",
- * "tag_code": "190419000002",
- * "tag_type": 1,
- * "tag_icon": "",
- * "tag_sequence": 1,
- * "tag_remark": "",
- * "created_at": 1555593200,
- * "updated_at": 1555593200,
- * "is_del": 0,
- * "children": [
- * {
- * "id": "4",
- * "platform": "",
- * "user": "",
- * "tag_name": "统货",
- * "tag_code": "190419000004",
- * "tag_type": 1,
- * "tag_icon": "",
- * "tag_sequence": 1,
- * "tag_remark": "",
- * "created_at": 1555593200,
- * "updated_at": 1555593200,
- * "is_del": 0,
- * }]
- * }]
- * "pagination": {
- * "total": 3,
- * "pageSize": 20,
- * "current": 1
- * }
- * },
- * "alertMsg": "标签列表查询成功"
- * }
- * @apiError 201006 标签不存在
- */
- public function actionListTree()
- {
- $params = Yii::$app->request->post();
- // $params['tag_code_path'] = '190419000001';
- // $params['deep'] = 2;
- if (!isset($params['user'])){
- $params['user'] = '';
- }
- if (!isset($params['tag_code_path'])){
- $params['tag_code_path'] = '';
- }
- if (!isset($params['deep'])){
- $params['deep'] = 0;
- }
- $result = TagService::listTree($params);
- // echo '<pre>';
- // print_r($result);
- // echo '</pre>';
- // die;
- return $this->responseData($result['data'], $result['code'], $result['msg']);
- }
- }
生成API文档
- cd f:
- cd project/chgg-user-service-api
- cd restapi
apidoc -i restapi/controllers/ -c restapi/web/ -o restapi/web/apidoc
解释:
- # 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脚本
- ./genapidoc.sh
- #具体内容为
apidoc -i restapi/controllers/ -c restapi/web/ -o restapi/web/apidoc
实例文档地址:
- http://tagdoc.test.chinahanguang.com/index.html
生成结果
更多示例
- /**
- * @apiDefine TestController 测试管理
- */
- /**
- *
- * @apiDeprecated 现在请使用(#Test:_test)
- * @api {post} /tag/test 01-测试
- * @apiGroup TestController
- * @apiName actionTest
- * @apiVersion 1.6.2
- * @apiPermission 无
- * @apiExample {curl} 使用curl
- * curl -i http://localhost/tag/test
- *
- * @apiHeader {String} access_token 授权令牌
- * @apiHeaderExample {json} 请求头示例
- * {
- * "access_token": "abcdddd78789a7t89e8t9t9ew8t7e89t89te"
- * }
- * @apiParam {String} [firstname] Optional 姓
- * @apiParam {String} lastname Mandatory 名
- * @apiParam {String} country="中国" Mandatory 国籍
- * @apiParam {Number} [age=18] Optional 年龄
- * @apiParam (Login) {String} pass 登录密码
- * @apiParamExample {json} 请求示例
- * {
- * "content": "This is an example content"
- * }
- * @apiSuccess {String} firstname 姓
- * @apiSuccessExample 返回示例
- * {
- * "code": 200000,
- * "ret": {
- * "id": 1,
- * "pid": "0",
- * "tag_name": "药材"
- * "tag_code": "0011"
- * },
- * "alertMsg": "创建标签成功!"
- * }
- * @apiSampleRequest http://www.example.com
- * @apiError 10001 缺少参数
- * @apiErrorExample {json} 错误示例
- * HTTP/1.1 404 Not Found
- * {
- * "error": "未找到用户"
- * }
- */
- public function actionTest()
- {
- }
APIDOC的使用的更多相关文章
- apidoc
1.安装node http://nodejs.cn/download/ 下载二进制包,解压,配置环境 export NODE_HOME=/usr/local/nodeexport PATH=$NODE ...
- 基于php开发的RESTful ApiDoc文档
apiDoc基于rest的web API文档生成器,可以根据代码注释生成web api文档,自动生成静态的html网页文档,不仅支持项目版本号,还支持API版本号. 使用apiDoc不需要自己麻烦的调 ...
- ApiDoc 文档使用方式
1.安装node.js 2.打开node.js 命令窗(shell)键入npm install apidoc -g 自动安装(几分钟) 3. C:\Users\user\AppData\Roaming ...
- apidoc,一个相当不错的文档生成器
http://apidocjs.com/ 例子:myapp目录下的MyCode.java /** * * @api {get} /company/list 获取公司信息 * @apiName 获取公司 ...
- webApi文档好帮手-apidoc使用教程
来源:http://blog.csdn.net/xumin198908/article/details/41964159 在开发后台接口的过程中,我们肯定要提供一份api接口文档给终端app. 目前大 ...
- 使用apidoc根据JS文件生成接口文档
1.安装nodejs.下载网址:http://www.nodejs.org: 2.安装apidoc.运行cmd,切换到nodejs的安装目录,在命令行输入: 1 npm install apidoc ...
- 关于apidoc文档生成不了的一个原因
前几天在写完API后,写注释文档,然后很习惯的去用apidoc取生成注释文档,但是奇怪的事发生了,没有注释的内容,也没有报错:注释代码如下: /* * @api {get} /applet/:id 根 ...
- apidoc快速生成在线文档,apidoc生成静态文件的生成规则以及原理分析
在老大的指引下,需要将系统的json文件格式转换成apidoc的json格式,也就是json格式的重组,但是这个apidoc的生成格式是不固定的,因为apidoc有自己一套的生成规则,我需要研究一下是 ...
- Node与apidoc的邂逅——NodeJS Restful 的API文档生成
作为后台根据需求文档开发完成接口后,交付给前台(angular vue等)做开发,不可能让前台每个接口调用都去查看你的后台代码一点点查找.前台开发若不懂你的代码呢?让他一个接口一个接口去问你怎么调用, ...
- 接口文档神器之apidoc
//@desn:apidoc linux环境 windows环境使用 //@desn:码字不宜,转载请注明出处 //@author:张慧源 <turing_zhy@163.com> / ...
随机推荐
- 【css】常用css
常用css--------下三角 常用css--------闪动效果 css #shandongFlash { width:100px; height:100px; background:#f8b55 ...
- Linux 分卷压缩
例如,要将大文件夹 PYNQ 分卷压缩成 1G 的单元大小,如下命令(类似的可以指定 tar 的参数为 czf 而生产 .tar.gz 格式的压缩包:可以指定分卷大小例如 500M 等),压缩完成后, ...
- leetcode 74. Search a 2D Matrix 、240. Search a 2D Matrix II
74. Search a 2D Matrix 整个二维数组是有序排列的,可以把这个想象成一个有序的一维数组,然后用二分找中间值就好了. 这个时候需要将全部的长度转换为相应的坐标,/col获得x坐标,% ...
- 最长上升子序列(LIS)
(我先扯些没用的) 我这个笨孩子 学点东西好慢好慢的 我还贪玩 于是 将自己陷入了一个超级超级超级差的境地 可 我还傻乎乎的保有着天真的梦想(理想?) 所以现在我要加倍的努力努力再努力了 只能嘎油了 ...
- 1-STM32带你入坑系列(STM32介绍)
由于自己的物联网开发板上的单片机是用的STM32,但是有些朋友没有用过,所以我将用这块开发板,带着大家入门STM32 先介绍一下STM32,我是在大三下学期的时候开始接触STM32,当时是想做一个小车 ...
- CISCO交换机-SNMP配置
1.1 SNMP基础配置 router> enable 进入路由器是用户模式 router# conf terminal 进入路由器的全局配置模式 #snmp-server commun ...
- 牛客网 Python 编程输入规范
import sys try: while True: line = sys.stdin.readline().strip() if line == '': break lines = line.sp ...
- Python-time模块-58
time 模块: Eva_J import time time.sleep(100) #时间睡眠 print(time.time()) #返回一个以秒为单位的时间 时间模块 和时间有关系的我们就要用到 ...
- java 接口实现防盗门功能
Door: package locker; public abstract class Door { public abstract void open(); public abstract void ...
- 出题人的RP值(牛客练习赛38--A题)(排序)
链接:https://ac.nowcoder.com/acm/contest/358/A来源:牛客网 题目描述 众所周知,每个人都有自己的rp值(是个非负实数),膜别人可以从别人身上吸取rp值. 然而 ...