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

    }

最新文章

  1. Github fork同步
  2. 教你如何塑造JavaScript牛逼形象
  3. SQL SERVER 2008：内部查询处理器错误: 查询处理器在执行过程中遇到意外错误
  4. MySQL 配置文件中忘配置default-character-set引发的乱码问题
  5. 「LAMP」在ubuntu及其衍生版上 安装LAMP
  6. C#中的Delegate
  7. [反汇编练习] 160个CrackMe之013
  8. win7下的mstsc ubuntu下的rdesktop
  9. Better Completion插件使用
  10. 从SQL2008R2导入数据到SQL2005
  11. C语言解析日志，存储数据到伯克利DB
  12. 关于PhpDE zend ide破解方式
  13. Java Web整合开发(4) -- JSP
  14. 基于JDK1.8的HashMap分析
  15. LPC 网络编程
  16. Java 集合系列（一）
  17. js05-DOM对象二
  18. java基础基础总结----- Date
  19. Python错误和异常 学习笔记
  20. python类的继承-1

热门文章

  1. js 文件引用传递参数
  2. P2080 增进感情（背包DP）
  3. 【转】ffmpeg常用基本命令
  4. element not interactable，这种提示表示元素当前在页面上不可见
  5. 【转】打包 压缩 命令tar zip
  6. 机器学习三剑客之Matplotlib基本操作
  7. pyspider环境部署1--python3安装
  8. 获取数值型数组的最大值和最小值，使用遍历获取每一个值，然后记录最大值和最小值的方式。（数组遍历嵌套if判断语句）
  9. 首页技术支持常见问题宽带外网IP显示为10、100、172开头，没有公网IP，如何解决？
  10. Java多线程学习(四)---控制线程