ApiDoc - marmot-cn/marmot-framework GitHub Wiki
接口文档主要提供接口名称、接口说明、路由、请求参数、响应参数等信息，方便人员查看和维护。
- 接口名称
- 接口说明
- 请求参数
- 响应参数
- 错误码
- 字段
- 说明
- 类型
- 是否必填
- 示例
见《错误规范》文件
# 用户接口示例
---
* [参考文档](#参考文档)
* [项目字典](#项目字典)
* [控件规范](#控件规范)
* [错误规范](#错误规范)
* [接口错误返回说明](#接口错误返回说明)
* [参数说明](#参数说明)
* [接口示例](#接口示例)
* [获取单条数据](#获取单条数据)
* [获取多条数据](#获取多条数据)
* [根据检索条件查询数据](#根据检索条件查询数据)
* [注册](#注册)
* [登录](#登录)
* [忘记密码](#忘记密码)
* [修改密码](#修改密码)
* [手机号换绑](#手机号换绑)
* [启用](#启用)
* [禁用](#禁用)
* [接口返回示例](#接口返回示例)
* [单条数据接口返回示例](#单条数据接口返回示例)
* [多条数据接口返回示例](#多条数据接口返回示例)
## <a name="参考文档">参考文档</a>
* <a name="项目字典">项目字典</a>
* [人通用项目字典](人通用项目字典.md "人通用项目字典")
* [用户项目字典](用户项目字典.md "用户项目字典")
* <a name="控件规范">控件规范</a>
* [人通用控件规范](人通用控件规范.md "人通用控件规范")
* [用户控件规范](用户控件规范.md "用户控件规范")
* <a name="错误规范">错误规范</a>
* [人通用错误规范](人通用错误规范.md "人通用错误规范")
* [用户错误规范](用户错误规范.md "用户错误规范")
* <a name="接口错误返回说明">接口错误返回说明</a>
* [接口错误返回说明](接口错误返回说明.md "接口错误返回说明")
## <a name="参数说明">参数说明</a>
<table>
<tr>
<th><b>字段</b></th>
<th><b>说明</b></th>
<th><b>类型</b></th>
<th><b>是否必填</b></th>
<th><b>示例</b></th>
</tr>
<tr>
<td>cellphone</td>
<td>手机号</td>
<td>string</td>
<td>是</td>
<td>18800000000</td>
</tr>
<tr>
<td>password</td>
<td>密码</td>
<td>string</td>
<td>是</td>
<td>Admin123</td>
</tr>
<tr>
<td>oldPassword</td>
<td>旧密码</td>
<td>string</td>
<td>是</td>
<td>Admin123</td>
</tr>
<tr>
<td>realName</td>
<td>真实姓名</td>
<td>string</td>
<td>是</td>
<td>张昊</td>
</tr>
<tr>
<td>passport</td>
<td>登录凭证。手机号或用户名</td>
<td>string</td>
<td>是</td>
<td>18800000000</td>
</tr>
<tr>
<td>avatar</td>
<td>头像</td>
<td>array</td>
<td>否</td>
<td>array("name" => "图片名称", "identify" => "图片标识")</td>
</tr>
<tr>
<td>userName</td>
<td>用户名。默认等于手机号</td>
<td>string</td>
<td></td>
<td>18800000000</td>
</tr>
<tr>
<td>authenticatingState</td>
<td>认证状态。未认证：0，已认证：2</td>
<td>int</td>
<td></td>
<td>0</td>
</tr>
<tr>
<td>status</td>
<td>状态。启用：0，禁用：-2</td>
<td>int</td>
<td></td>
<td>0</td>
</tr>
</table>
## <a name="接口示例">接口示例</a>
### 获取数据支持include、fields请求参数
1、include请求参数
2、fields[TYPE]请求参数
2.1 fields[members]
3、page请求参数
3.1 page[number]=1 | 当前页
3.2 page[size]=20 | 获取每页的数量
示例
$response = $client->request('GET', 'members/1?fields[members]=cellphone,realName',['headers'=>['Content-' => 'application/vnd.api+json']]);
### <a name="获取单条数据">获取单条数据示例</a>
路由
通过GET传参
/members/{id:\d+}
示例
$response = $client->request('GET', 'members/1',['headers'=>['Content-' => 'application/vnd.api+json']]);
### <a name="获取多条数据">获取多条数据示例</a>
路由
通过GET传参
/members/{ids:\d+,[\d,]+}
示例
$response = $client->request('GET', 'members/1,2,3',['headers'=>['Content-' => 'application/vnd.api+json']]);
### <a name="根据检索条件查询数据">根据检索条件查询数据示例</a>
路由
通过GET传参
/members
1、检索条件
1.1 filter[cellphone] | 根据手机号搜索
1.2 filter[authenticatingState] | 根据认证状态搜索 | 未认证 0 | 已认证 2
1.3 filter[status] | 根据状态搜索 | 启用 0 | 禁用 -2
2、排序
2.1 sort=-id | -id 根据id倒序 | id 根据id正序
2.2 sort=-updateTime | -updateTime 根据更新时间倒序 | updateTime 根据更新时间正序
示例
$response = $client->request('GET', 'members?filter[authenticatingState]=2&sort=-id&page[number]=1&page[size]=20',['headers'=>['Content-' => 'application/vnd.api+json']]);
### <a name="注册">注册示例</a>
路由
通过POST传参
/members
示例
$data = array("data"=>array(
"type"=>"members",
"attributes"=>array(
"cellphone"=>"18800000000",
"password"=>"123456"
)
)
);
$response = $client->request(
'POST',
'members',
[
'headers'=>['Content-Type' => 'application/vnd.api+json'],
'json' => $data
]
);
### <a name="登录">登录示例</a>
路由
通过POST传参
/members/signIn
示例
$data = array("data"=>array(
"type"=>"members",
"attributes"=>array(
"passport"=>"18800000000",
"password"=>"123456"
)
)
);
$response = $client->request(
'POST',
'members/signIn',
[
'headers'=>['Content-Type' => 'application/vnd.api+json'],
'json' => $data
]
);
### <a name="忘记密码">忘记密码示例</a>
路由
通过PATCH传参
/members/resetPassword
示例
$data = array("data"=>array(
"type"=>"members",
"attributes"=>array(
"cellphone"=>"18800000000",
"password"=>"123456"
)
)
);
$response = $client->request(
'PATCH',
'members/resetPassword',
[
'headers'=>['Content-Type' => 'application/vnd.api+json'],
'json' => $data
]
);
### <a name="修改密码">修改密码示例</a>
路由
通过PATCH传参
/members/{id:\d+}/updatePassword
示例
$data = array("data"=>array(
"type"=>"members",
"attributes"=>array(
"oldPassword"=>"123456",
"password"=>"12345678"
)
)
);
$response = $client->request(
'PATCH',
'members/1/updatePassword',
[
'headers'=>['Content-Type' => 'application/vnd.api+json'],
'json' => $data
]
);
### <a name="手机号换绑">手机号换绑示例</a>
路由
通过PATCH传参
/members/{id:\d+}/updateCellphone
示例
$data = array("data"=>array(
"type"=>"members",
"attributes"=>array(
"cellphone"=>"1880000001"
)
)
);
$response = $client->request(
'PATCH',
'members/1/updateCellphone',
[
'headers'=>['Content-Type' => 'application/vnd.api+json'],
'json' => $data
]
);
### <a name="启用">启用示例</a>
路由
通过PATCH传参
/members/{id:\d+}/enable
示例
$response = $client->request('PATCH', 'members/1/enable',['headers'=>['Content-' => 'application/vnd.api+json']]);
### <a name="禁用">禁用示例</a>
路由
通过PATCH传参
/members/{id:\d+}/disable
示例
$response = $client->request('PATCH', 'members/1/disable',['headers'=>['Content-' => 'application/vnd.api+json']]);
### <a name="接口返回示例">接口返回示例</a>
#### <a name="单条数据接口返回示例">单条数据接口返回示例</a>
{
"meta": [],
"data": {
"type": "members",
"id": "1",
"attributes": {
"cellphone": "1880000001",
"userName": "1880000001",
"realName": "张良",
"avatar": {
"name": "name",
"identify": "identify"
},
"authenticatingState": 2,
"status": 0
},
"links": {
"self": "127.0.0.1:8081\/members\/1"
}
}
}
#### <a name="多条数据接口返回示例">多条数据接口返回示例</a>
{
"meta": {
"count": 3,
"links": {
"first": 1,
"last": 2,
"prev": null,
"next": 2
}
},
"links": {
"first": "127.0.0.1:8081\/members?sort=-id&page[number]=1&page[size]=2",
"last": "127.0.0.1:8081\/members?sort=-id&page[number]=2&page[size]=2",
"prev": null,
"next": "127.0.0.1:8081\/members?sort=-id&page[number]=2&page[size]=2"
},
"data": [
{
"type": "members",
"id": "3",
"attributes": {
"cellphone": "1880000003",
"userName": "1880000003",
"realName": "吴敏",
"avatar": {
"name": "name",
"identify": "identify"
},
"authenticatingState": 2,
"status": 0
},
"links": {
"self": "127.0.0.1:8081\/members\/3"
}
},
{
"type": "members",
"id": "2",
"attributes": {
"cellphone": "1880000002",
"userName": "1880000002",
"realName": "李磊",
"avatar": {
"name": "name",
"identify": "identify"
},
"authenticatingState": 2,
"status": 0
},
"links": {
"self": "127.0.0.1:8081\/members\/2"
}
}
]
}