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> / ...
随机推荐
- mysql 使用正则表达式查询
SELECT * FROM `qq` where qq_name!='no' and qq_gender='女' and qq_location!='no' and qq_location!='' a ...
- Python：margin collapse
margin collapse:边界 折叠/重叠/坍塌 此种现象只会垂直方向并且要满足一定条件时才会出现这种现象. https://tech.youzan.com/css-margin-collaps ...
- AppCan10个超实用的APP必备插件，让你少敲80%代码
一个APP的需求来自于哪儿?产品.老板.客户….. 做程序员不容易,需求一句话,就是几千几万行代码!所幸,在AppCan平台开发APP,开发者只需完成应用的前端部分,至于各项复杂的功能,就交给AppC ...
- Redis可视化客户端管理及监控工具TreeNMS
https://www.cnblogs.com/li150dan/p/9529054.html
- ssh 免密码登录配置，及其原理
1.废话不多说,先上图 2. 典型的RSA非对称加密 RSA加密算法是一种典型的非对称加密算法,它基于大数的因式分解数学难题,它也是应用最广泛的非对称加密算法,于1978年由美国麻省理工学院(MI ...
- js 原生ajax实现
<!DOCTYPE html> <html> <head> <meta http-equiv="Content-Type" content ...
- java连接Mysql8
相较于之前版本会有部分改动 pom依赖 <dependency> <groupId>mysql</groupId> <artifactId>mysql- ...
- asp.net调用前台js调用后台代码分享
asp.net调用前台js调用后台代码分享 C#前台js调用后台代码前台js<script type="text/javascript" language="jav ...
- JSF生存指南P1
这是OO的第三次博客作业,也是JSFO(面向JSF编程)的第一次博客作业.暗示了我们面向对象课程已经再向JSF的编写过渡. 不知不觉OO的作业已经写完3/4,那些熬夜赶作业的日子仍然历历在目,仿佛是昨 ...
- OO博客作业4：第13-14周作业总结
一.论述测试与正确性论证的效果差异,比较其优缺点 测试是设计若干组测试用例,运行程序并检验其是否完成预期功能.测试是一种直接发现BUG的方法,可以准确断定什么样的BUG会发生,并通过辅助调试进一步确定 ...