添加简略的接口文档,准备使用srping重写

spring-dev
lensfrex 3 years ago
parent 4384fa7342
commit 2a4228d0e1
Signed by: lensfrex
GPG Key ID: 0F69A0A2FBEE98A0
  1. 166
      API_doc.md

@ -0,0 +1,166 @@
# Trailblazer RESTful API 文档
---
##### 本文档中,除非特殊说明,URL测试地址均为 https://lb.ciduid.top ,使用POST方法的API参数均为Body部分的参数,以json格式发送
## 用户相关
### 1. 登录
- 功能:登录一个已经存在的用户,获取会话token
- URL: `/api/v1/login`
- 方法:`POST`
- 参数:
| 参数 | 参数类型 | 说明 |
| --------- | ------ | ---------------------------------------- |
| user_name | string | 登录用户名,必选 |
| password | string | 一次sha256后,再在尾部拼接原始密码,然后再一次sha256得到的密文,必选 |
| verify | string | 验证码,可选,在服务器要求的时候需要提供,目前没有用 |
示例:
```json
{
"user_name": "userName",
"password": "57a8a929b8fc077da76769179159a1d3ae44e9f255c270fc98d4b125b30d5cca",
"verify": "114514"
}
```
- 返回:
- | 字段 | 字段类型 | 说明 |
| ------------ | ------ | ------------------------------------------- |
| code | int | 请求的状态信息码,详见“状态信息码” |
| msg | string | 本次请求的信息 |
| uid | int | 用户的uid |
| access_token | string | 会话token,用于其他API调用,成功时返回正确token,不成功时为null |
| expired_at | string | token过期时间,应当在token过期前调用token续期API以获取新的token |
### 2. 注册
- 功能:注册创建一个账号
- URL:`/api/v1/register`
- 方法:`POST`
- 参数:
| 参数 | 参数类型 | 说明 |
| --------- | ------ | -------------------------------------------------- |
| user_name | string | 注册的用户名,用于登录,最长不超过32位,必选 |
| password | string | 第一次sha256后再在尾部拼接原始密码,然后再一次sha256得到的密文,长度应为8~32位,必选 |
| verify | string | 验证码,可选,在服务器要求的时候需要提供,目前没有用 |
示例:
```json
{
"user_name": "userName",
"password": "57a8a929b8fc077da76769179159a1d3ae44e9f255c270fc98d4b125b30d5cca",
"verify": "114514"
}
```
- 返回:
- | 字段 | 字段类型 | 说明 |
| ---------- | ------ | ------------------------------------------- |
| code | int | 请求的状态信息码,详见“状态信息码” |
| msg | string | 本次请求的信息 |
| uid | int | 用户uid |
| token | string | 会话token,用于其他API调用,成功时返回正确token,不成功时为null |
| expired_at | string | token过期时间,应当在token过期前调用token续期API以获取新的token |
### 3. 修改用户基本信息
// 这里的接口还没想好怎么设计
- 功能:修改用户的基本信息,如密码、登录名等
- URL:`/api/v1/modifyUserBasicInfo?uid={uid}`
- 方法:`post`
- 参数:
- | 参数 | 参数类型 | 说明 |
| --------- | ------ | ----------------------- |
| uid | int | 欲修改的用户的uid,必选 |
| user_name | string | 注册的用户名,用于登录,最长不超过32位,必选 |
| token | string | 登陆时获得的token,必选 |
示例:
```json
{
"user_name": "userName",
"token": "57a8a929b8fc077da76769179159a1d3ae44e9f255c270fc98d4b125b30d5cca", ""
}
```
### 4. 修改用户个性信息
- 功能:修改用户的基本信息,如密码、登录名等
- URL:`/api/v1/modifyUserInfo?uid={uid}`
- 方法:`post`
- 参数:
- | 参数 | 参数类型 | 说明 |
| ------------ | ------ | ------------------------- |
| uid | int | 欲修改的用户的uid,放置于请求URL参数中,必选 |
| token | string | 有效的会话token,必选 |
| modify_tiems | json | 欲更改的个性数据信息 |
- 返回:
- | 字段 | 字段类型 | 说明 |
| ------ | --------- | ------------ |
| code | int | 状态信息码 |
| msg | string | 结果信息 |
| result | jsonArray | 更改后用户的完整个性信息 |
### 5. 获取用户个性信息
- 功能:修改用户的基本信息,如密码、登录名等
- URL:`/api/v1/profile?uid={uid}`
- 方法:`get`
- 参数:
- | 参数 | 参数类型 | 说明 |
| ----- | ------ | --------------------------- |
| uid | int | 欲获取的用户的uid,放置于请求URL参数中,必选 |
| token | string | 有效的会话token,可选,若不提供仅能显示公开的信息 |
- 返回:
- | 字段 | 字段类型 | 说明 |
| ------ | --------- | ------ |
| code | int | 状态信息码 |
| msg | string | 结果信息 |
| result | jsonArray | 获取到的信息 |
> 4、5中用户信息result字段的json结构:
>
> ```json
> [
> "nick_name": "lensfrex",
> "desc": null,
> ...
> ]
> ```
*~~先这样吧~~*
Loading…
Cancel
Save