# 自动生成接口文档
接着上一步的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":"密码错误"
}
```