工具名称：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()
{
}