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

2 years ago · 68da8ec4d5
parent 4384fa7342
commit 68da8ec4d5
1 changed files with 166 additions and 0 deletions
--- a/API_doc.md
+++ b/API_doc.md
@ -0,0 +1,166 @@
+# Trailblazer RESTful API 文档
+
+---
+
+##### 本文档中，除非特殊说明，URL测试地址均为 https://lb.ciduid.topa  ，使用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,
+>     ...
+> ]
+> ```
+
+*~~先这样吧~~*