自動生成接口文檔 · tp5-smart開發模式

# 自動生成接口文檔接著上一步的UserController.php來繼續開發。我們先命令行創建一個用戶 ```php php public/index.php api/user/create ``` 返回值 ```json {"status":-1,"message":"name為必填項","data":[]} ``` 為什么會報這個錯誤呢？我們看下數據庫定義。 ```sql CREATE TABLE `user` ( `id` int(11) NOT NULL AUTO_INCREMENT, `name` varchar(255) NOT NULL DEFAULT '' COMMENT '{"verifies":["is_required","chinese"],"name":"名稱"}', `password` varchar(255) NOT NULL DEFAULT '' COMMENT '{"verifies":["is_required",["password",6,18]],"store_format":["password","aaa"],"name":"密碼"}', PRIMARY KEY (`id`) ) ENGINE=InnoDB AUTO_INCREMENT=2 DEFAULT CHARSET=utf8 COMMENT='{"name":"用戶表","create_api":["getList","get","create","delete","update"]}'; ``` name的verifies中定義了is_required，必填項，所以會自動報錯。 ```php php public/index.php api/user/create/name/zhangsan ``` 返回值為 ```json {"status":-1,"message":"name:zhangsan 中文格式錯誤","data":{"name":"zhangsan"}} ``` 同理，verifies中定義了中文的校驗判斷。我們傳一個中文名稱 ```php php public/index.php api/user/create/name/張三 ``` 返回值 ```json {"status":-1,"message":"password為必填項","data":{"name":"張三"}} ``` 因為，password也是必填值。再次執行 ```php php public/index.php api/user/create/name/張三/password/123 ``` 返回值 ```json {"status":-1,"message":"password:123 密碼長度6~18，且只能包含字符、數字和下劃線","data":{"name":"張三","password":"123"}} ``` 校驗均是自動完成，其實只要定義好了數據庫DLL，其實很多的開發工作量都可以省略。創建一個真實的用戶 ```php php public/index.php api/user/create/name/張三/password/123456 ``` ```json {"status":"api-user-create-1","id":"1"} ``` 返回的id=1是數據庫存儲的主鍵id。看下數據庫記錄 ```sql -- ---------------------------- -- Records of user -- ---------------------------- INSERT INTO `user` VALUES ('1', '張三', '93a9e5bb1d598a453606e890f72bd393'); ``` 其中密碼93a9e5bb1d598a453606e890f72bd393也是自動生成的。93a9e5bb1d598a453606e890f72bd393 = md5('123456'+'aaa');aaa字符串是，數據庫定義的，可以修改為任何自己想要的值。 ### 單元測試，上一步新增的login接口 ```php php public/index.php api/user/login ``` 返回值 ```json {"status":-1,"message":"name為必填項","data":{"name":null}} ``` 是因為，我們在login接口中定義了verifyIsRequire ```php $name = get_param('name', ClFieldVerify::instance() ->verifyIsRequire() ->verifyChinese() ->fetchVerifies() ); ``` 測試三種情況 1. 密碼正確 ```php php public/index.php api/user/login/name/張三/password/123456 ``` 返回值 ```json {"status":"api-user-login-2","message":"登錄成功","user_info":{"id":1,"name":"張三","password":"93a9e5bb1d598a453606e890f72bd393"}} ``` 將該返回值，復制粘貼到UserController中 ```php return $this->ar(2, ['message' => '登錄成功', 'user_info' => $user_info], '{"status":"api-user-login-2","message":"登錄成功","user_info":{"id":1,"name":"張三","password":"93a9e5bb1d598a453606e890f72bd393"}}'); ``` 2. 密碼錯誤 ```php php public/index.php api/user/login/name/張三/password/123457 ``` 返回值 ```json {"status":"api-user-login-3","message":"密碼錯誤"} ``` 將該返回值，復制粘貼到UserController中 ```php return $this->ar(3, ['message' => '密碼錯誤'], '{"status":"api-user-login-3","message":"密碼錯誤"}'); ``` 3. 不存在賬號 ```php php public/index.php api/user/login/name/李四/password/123456 ``` 返回值 ```json {"status":"api-user-login-1","message":"不存在當前賬號"} ``` 將該返回值，復制粘貼到UserController中 ```php return $this->ar(1, ['message' => '不存在當前賬號'], '{"status":"api-user-login-1","message":"不存在當前賬號"}'); ``` 此時，接口login變成了 ```php <?php /** * Created by PhpStorm. * User: SmartInit * Date: 2018/01/23 * Time: 10:13:26 */ namespace app\api\controller; use app\api\base\UserBaseApiController; use app\index\model\UserModel; use ClassLibrary\ClFieldVerify; /** * 用戶表 * 如果有需要，請重寫父類接口，不可直接修改父類函數，會被自動覆蓋掉。 * Class UserController * @package app\api\controller */ class UserController extends UserBaseApiController { /** * 登錄 * @return \think\response\Json|\think\response\Jsonp * @throws \think\db\exception\DataNotFoundException * @throws \think\db\exception\ModelNotFoundException * @throws \think\exception\DbException */ public function login(){ $name = get_param('name', ClFieldVerify::instance() ->verifyIsRequire() ->verifyChinese() ->fetchVerifies() ); $password = get_param('password', ClFieldVerify::instance() ->verifyIsRequire() ->verifyIsPassword() ->fetchVerifies() ); //獲取用戶信息 $user_info = UserModel::instance()->where([ UserModel::F_NAME => $name ])->find(); if(empty($user_info)){ return $this->ar(1, ['message' => '不存在當前賬號'], '{"status":"api-user-login-1","message":"不存在當前賬號"}'); }else{ if(UserModel::verifyPassword($user_info[UserModel::F_PASSWORD], $password)){ //拼接額外字段 & 格式化相關字段 $user_info = UserModel::forShow($user_info); return $this->ar(2, ['message' => '登錄成功', 'user_info' => $user_info], '{"status":"api-user-login-2","message":"登錄成功","user_info":{"id":1,"name":"張三","password":"93a9e5bb1d598a453606e890f72bd393"}}'); }else{ return $this->ar(3, ['message' => '密碼錯誤'], '{"status":"api-user-login-3","message":"密碼錯誤"}'); } } } } ``` ### 生成api 執行命令 ```php php think api_doc ``` 輸出 ```php /webroot/thinkphp_test/application/api/controller/UserController.php create /webroot/thinkphp_test/doc/api/18.01.20.23.22.html ok. ``` 這個時候，在doc/api目錄下生成了一個html格式的api文檔，文件名為生成的時間。 #### 格式大致如下 1. 用戶表 / 登錄請求地址: ``` /api/user/login ``` 參數: 名稱 | 校驗條件 | 描述 ---|---|--- name|必填; 中文|- password|必填; 密碼長度6~18|- api_include_example|數字; 在["0","1"]范圍內|返回值是否包含例子返回值: ```json { "status":"api-user-login-1", "message":"不存在當前賬號" } ``` ```json { "status":"api-user-login-2", "message":"登錄成功", "user_info":{ "id":1, "name":"張三", "password":"93a9e5bb1d598a453606e890f72bd393" } } ``` ```json { "status":"api-user-login-3", "message":"密碼錯誤" } ```