支持 apidoc 生成 REST 文档

.gitignore

@@ -6,3 +6,5 @@ public/install/install.lock
 *.xlsx
 *.xls
 *.pid
+docs/api_admin
+docs/api_front

app/api/controller/AuthController.php

@@ -27,13 +27,28 @@ use think\facade\Session;
  */
 class AuthController
 {
+
     /**
-     * H5账号登陆
-     * @param Request $request
-     * @return mixed
-     * @throws \think\db\exception\DataNotFoundException
-     * @throws \think\db\exception\ModelNotFoundException
-     * @throws \think\exception\DbException
+     * @api {post} /login H5账号登陆
+     * @apiName Login
+     * @apiGroup Login
+     * 
+     * @apiBody {string} account 輸入帐号.
+     * @apiBody {string} password 輸入密碼(明文).
+     * @apiBody {int} [spread] 上级 UID
+     * 
+     * @apiSuccessExample Success-Response:
+     *  HTTP/1.1 200 OK
+     *  {
+     *      "token": "xxxcvc",
+     *      "expires_time": "2000-11-01 08:09:10"
+     *  }
+     * 
+     * @apiErrorExample {json} Error-Response:
+     *  {
+     *      "status":400,
+     *      "msg": ["账号或密码错误", "已被禁止，请联系管理员","登录失败"]
+     *  }
      */
     public function login(Request $request)
     {
@@ -64,8 +79,22 @@ class AuthController
     }
 
     /**
-     * 退出登录
-     * @param Request $request
+     * @api {get} /logout 退出登录
+     * @apiName Logout
+     * @apiGroup User
+     * 
+     * @apiSuccessExample Success-Response:
+     *  HTTP/1.1 200 OK
+     *  {
+     *      "status": 200
+     *      "msg": "成功"
+     *  }
+     * 
+     * @apiErrorExample Error-Response:
+     * {
+     *      "status": 410000,
+     *      "msg": "请登录"
+     * }
      */
     public function logout(Request $request)
     {
@@ -73,6 +102,20 @@ class AuthController
         return app('json')->success('成功');
     }
 
+    /**
+     * @api {get} /verify_code 获取发短信的 KEY
+     * @apiName GetVerificationCode
+     * @apiGroup Login 
+     *
+     * @apiSuccessExample Success-Response:
+     * {
+     *  "status": 200,
+     *  "key": "dfsdfdsfdg"
+     * }
+     * 
+     * @apiDeprecated 先获取 key 再发短信没用，并不能防止客户端脚本。起码要先获取验证码，用户输入验证码再发短信。
+     * 因为现在短信平台都有防攻击机制，这方面的功能暂时不做。
+     */
     public function verifyCode()
     {
         $unique = password_hash(uniqid(true), PASSWORD_BCRYPT);
@@ -81,6 +124,16 @@ class AuthController
         return app('json')->success(['key' => $unique]);
     }
 
+    /**
+     * @api {get} /sms_captcha 获取发送短信的验证码
+     * @apiName GetSmsCaptcha
+     * @apiGroup Login
+     * 
+     * @apiSuccessExample Success-Response:
+     * 二进制图片信息
+     * 
+     * @apiDeprecated: 不再返回二进制信息，对于简单的二维码，直接返回 base64 编码的图片内容
+     */
     public function captcha(Request $request)
     {
         ob_clean();
@@ -122,13 +175,33 @@ class AuthController
     }
 
     /**
-     * 验证码发送
-     * @param Request $request
-     * @return mixed
+     * @api {post} /register/verify 验证码发送SMS
+     * @apiName PostRegisterVerify
+     * @apiGroup Login
+     * 
+     * @apiBody {string} phone 手机号
+     * @apiBody {string="register","login"} type
+     * @apiBody {string} code   用户识别验证码后的值
+     * @apiBody {string} key   通过 /verify_code 得到的 KEY
+     * 
+     * @apiSuccessExample:
+     * {
+     *  "status": 200,
+     *  "msg": "发送成功"
+     * }
+     * @apiErrorExample:
+     * {
+     *  "status": 400,
+     *  "msg": "error msg"
+     * }
      */
     public function verify(Request $request)
     {
-        list($phone, $type, $key, $code) = UtilService::postMore([['phone', 0], ['type', ''], ['key', ''], ['code', '']], $request, true);
+        list($phone, $type, $key, $code) = UtilService::postMore([
+            ['phone', ''], 
+            ['type', ''], 
+            ['key', ''], 
+            ['code', '']], $request, true);
 
         $keyName = 'sms.key.' . $key;
         $nowKey = 'sms.' . date('YmdHi');
@@ -185,13 +258,33 @@ class AuthController
     }
 
     /**
-     * H5注册新用户
-     * @param Request $request
-     * @return mixed
+     * @api {post} /register H5注册新用户
+     * @apiName PostRegister
+     * @apiGroup Login
+     * 
+     * @apiBody {string} account 帐号，手机号
+     * @apiBody {string} captcha    短信验证码
+     * @apiBody {string{6,16}} password   密码
+     * @apiBody {int} [spread] 推广上级
+     * 
+     * @apiSuccessExample:
+     * {
+     *  "status": 200,
+     *  "msg": "注册成功"
+     * }
+     * @apiErrorExample:
+     * {
+     *  "status": 400,
+     *  "msg": "error msg"
+     * }
      */
     public function register(Request $request)
     {
-        list($account, $captcha, $password, $spread) = UtilService::postMore([['account', ''], ['captcha', ''], ['password', ''], ['spread', 0]], $request, true);
+        list($account, $captcha, $password, $spread) = UtilService::postMore([
+            ['account', ''], 
+            ['captcha', ''], 
+            ['password', ''], 
+            ['spread', 0]], $request, true);
         try {
             validate(RegisterValidates::class)->scene('register')->check(['account' => $account, 'captcha' => $captcha, 'password' => $password]);
         } catch (ValidateException $e) {
@@ -212,13 +305,31 @@ class AuthController
     }
 
     /**
-     * 密码修改
-     * @param Request $request
-     * @return mixed
+     * @api {post} /register/reset 重置密码
+     * @apiName PostRegisterReset
+     * @apiGroup Login
+     * 
+     * @apiBody {string} account 帐号手机号
+     * @apiBody {string} captcha 短信验证码
+     * @apiBody {string} password 新密码
+     * 
+     * @apiSuccessExample:
+     * {
+     *  "status": 200,
+     *  "msg": "修改成功"
+     * }
+     * @apiErrorExample:
+     * {
+     *  "status": 400,
+     *  "msg": "error msg"
+     * }
      */
     public function reset(Request $request)
     {
-        list($account, $captcha, $password) = UtilService::postMore([['account', ''], ['captcha', ''], ['password', '']], $request, true);
+        list($account, $captcha, $password) = UtilService::postMore([
+            ['account', ''], 
+            ['captcha', ''], 
+            ['password', '']], $request, true);
         try {
             validate(RegisterValidates::class)->scene('register')->check(['account' => $account, 'captcha' => $captcha, 'password' => $password]);
         } catch (ValidateException $e) {
@@ -239,12 +350,25 @@ class AuthController
     }
 
     /**
-     * 手机号登录
-     * @param Request $request
-     * @return mixed
-     * @throws \think\db\exception\DataNotFoundException
-     * @throws \think\db\exception\ModelNotFoundException
-     * @throws \think\exception\DbException
+     * @api {post} /login/mobile 手机号登录
+     * @apiName PostLoginMobile
+     * @apiGroup Login
+     * 
+     * @apiBody {string} phone: 手机号
+     * @apiBody {string} captcha: 验证码
+     * @apiBody {int} [spread]: 推广上级
+     * 
+     * @apiSuccessExample Success-Response:
+     * {
+     *  "token": "xxdfgfgfg",
+     *  "expires_time": "2020-01-01 10:11:23"
+     * }
+     * 
+     * @apiErrorExample Error-Response:
+     * {
+     *  "status": 400,
+     *  "msg": "error msg"
+     * }
      */
     public function mobile(Request $request)
     {
@@ -285,12 +409,26 @@ class AuthController
     }
 
     /**
-     * H5切换登陆
-     * @param Request $request
-     * @return mixed
-     * @throws \think\db\exception\DataNotFoundException
-     * @throws \think\db\exception\ModelNotFoundException
-     * @throws \think\exception\DbException
+     * @api {post} /switch_h5 H5切换帐号登陆
+     * @apiName SwitchH5
+     * @apiGroup User
+     * 
+     * @apiBody {string} from 客户端类型 h5
+     * 
+     * @apiSuccessExample Success-Response:
+     * {
+     *  "userinfo": {
+     *  },
+     *  "token": "xxdfdg",
+     *  "expires_time": ""
+     * }
+     * @apiErrorExample Error-Response:
+     * {
+     *  "status": 400,
+     *  "msg": "error msg"
+     * }
+     * 
+     * @apiDeprecated 不用切换帐号，切啥切？退出重新登录
      */
     public function switch_h5(Request $request)
     {
@@ -346,12 +484,24 @@ class AuthController
     }
 
     /**
-     * 绑定手机号
-     * @param Request $request
-     * @return mixed
-     * @throws \think\db\exception\DataNotFoundException
-     * @throws \think\db\exception\ModelNotFoundException
-     * @throws \think\exception\DbException
+     * @api {post} /binding 绑定手机号
+     * @apiName PostBinding
+     * @apiGroup User
+     * 
+     * @apiBody {string} phone 绑定的手机号
+     * @apiBody {string} captcha 验证码
+     * @apiBody {int} [step] 已绑定是否支持重复绑定 1 支持 0 不支持
+     * 
+     * @apiSuccessExample:
+     * {
+     *  "status": 200
+     * }
+     * 
+     * @apiErrorExample:
+     * {
+     *  "status": 400,
+     *  "msg": "error msg"
+     * }
      */
     public function binding_phone(Request $request)
     {
@@ -395,8 +545,35 @@ class AuthController
             return app('json')->fail('绑定失败');
     }
 
-    /** 不登录模拟推送
-     * @param Request $request
+    /** 
+     * @api {get} /notifications 不登录模拟推送
+     * @apiName GetNotifications
+     * @apiGroup Message
+     * 
+     * @apiSuccessExample:
+     * {
+     *  "status": 200,
+     *  "msg": "ok",
+     *  "data": {
+     *      "carousel": [
+     *          {
+     *              "id": 1,
+     *              "info": "text",
+     *              "url": "page/boards",
+     *              "wap_url": "h5 front router",
+     *              "show": '2'
+     *          }
+     *      ]
+     *  }
+     * }
+     * @apiErrorExample:
+     * {
+     *  "status": 200,
+     *  "msg": "ok",
+     *  "data": {
+     *      "carousel": []
+     *  }
+     * }
      */
     public function notifications(Request $request)
     {

docs/apidoc.json

@@ -0,0 +1,13 @@
+{
+    "name": "twong client API",
+    "version": "1.2.5",
+    "description": "cross-client usage",
+    "header": {
+        "title": "api header",
+        "filename": "api_header.md"
+    },
+    "footer": {
+        "title": "api footer",
+        "filename": "api_footer.md"
+    }
+}

docs/gendoc.sh

@@ -0,0 +1,3 @@
+#!/usr/bin/env bash
+apidoc -i ../app/api -o api_front
+apidoc -i ../app/admin -o api_admin

docs/一次性工作.md

@@ -0,0 +1,15 @@
+## 删除所有用户订单以及佣金
+
+清除测试数据，但不清除系统赠送
+
+1. store_order
+2. store_order_batch
+3. store_order_cart_info
+4. store_order_status
+5. store_cart
+6. user.brokerage_price
+7. user_bill 部分条目
+8. user_extrace
+9. user_notice 用户相关条目
+10. user_notice_see 用户相关条目
+11. user_reward_order 相关条目