更新api文档

2 years ago · 9b92a98749
parent 57e1567977
commit 9b92a98749
1 changed files with 222 additions and 60 deletions
--- a/API-Document.md
+++ b/API-Document.md
@ -19,7 +19,8 @@
 | code | 信息 |
 | --- | --- |
 | 20000 | 成功 |
-| 30000 | 参数错误
+| 30000 | 参数错误 |
+| 30001 | token过期 |
 | 40300 | 权限不足 |
 | 40000 | 非法请求 |
 | 50000 | 服务器内部错误 |
@ -35,10 +36,10 @@

 - 请求参数：

-    | 参数 | 值类型 | 说明 |
-    | --- | --- | --- | 
-    | userName | string | 用户登录名，非空 |
-    | password | string | 用户登录密码，非空，其值为明文密码两次sha256加密 |
+    | 参数 | 值类型 | 可空 | 说明 |
+    | --- | --- | --- | --- | 
+    | userName | string | false |用户登录名，非空 |
+    | password | string | false |用户登录密码，非空，其值为明文密码两次sha256加密 |

    例如：
    ``` json
@ -50,7 +51,7 @@

 - 返回数据
  
-    | 字段 | 值类型 | 说明 |
+    | 参数 | 值类型 | 说明 |
    | --- | --- | --- | 
    | uid | string | 用户对应的uid |
    | role | int | 用户权限类型，0：普通用户，1：管理员 |
@ -78,43 +79,41 @@
    | --- | --- |
    | 40301 | 用户名或密码错误 |
    | 40302 | 用户已被封禁 |
+    | 40305 | 上级管理员未认证该用户 |

 ---

-### 用户注册
+### 用户注册（公共）

-> 普通用户并不提供注册功能，只能由管理员添加
+> 用户注册可由管理员手动创建，也可以由用户自行注册，但是需要提供管理员名称，并且由管理员确认信息后才能使用
 >
-> 在系统中首次注册的用户即为管理员，管理员注册后注册接口将不会处理任何非管理员请求，只能由管理员用户请求
+> 在系统中首次注册的用户即为管理员，管理员注册后普通用户必须要提供上级管理员才能注册

 - URL路径：`/user/register`
 - 方法：`POST`

 - 请求参数：

-    | 参数 | 值类型 | 说明 |
-    | --- | --- | --- | 
-    | userName | string | 用户登录名，非空 |
-    | password | string | 用户登录密码，非空，其值为明文密码两次sha256加密 |
-    | role | int | 用户角色，该选项只能由管理员使用，其他用户提供不生效 |
-    | token | string(header) | 管理员的access_token，如不提供且已经有初始管理员则会导致请求失败（权限不足） |
+    | 参数 | 值类型 | 可空 | 说明 |
+    | --- | --- | --- | --- | 
+    | userName | string | false | 用户登录名，非空 |
+    | password | string | false | 用户登录密码，非空，其值为明文密码两次sha256加密 |
+    | superior | string | true | 上级管理员用户名 |

    例如：
    ``` json
    {
        "userName": "admin",
        "password": "e723fb2ff93afb010960ac20c05439f1cdd1ecbb533947e7de9f43656a612052",
-        "role": 0
+        "superior": "lensfrex"
    }
    ```

 - 返回数据
  
-    | 字段 | 值类型 | 说明 |
+    | 参数 | 值类型 | 说明 |
    | --- | --- | --- | 
    | uid | string | 用户对应的uid |
-    | role | int | 用户权限类型，0：普通用户，1：管理员 |
-

    例如：
    ``` json
@ -122,16 +121,19 @@
        "code": 20000,
        "msg": "success",
        "data" : {
-            "uid": "9a6d777c-997d-a7e5-35f4-8471b7582ac0",
-            "role": 0
+            "uid": "9a6d777c-997d-a7e5-35f4-8471b7582ac0"
        }
    }
    ```
+
 - 错误信息

    | code | 错误 |
    | --- | --- |
    | 40300 | 权限不足 |
+    | 20001 | 用户已存在 |
+
+> 管理员添加用户，详见[添加用户](#添加用户)

 ---

@ -144,12 +146,12 @@

 - 请求参数：

-    | 参数 | 值类型 | 说明 |
-    | --- | --- | --- | 
-    | pid | string | 患者数据id |
-    | ctdna | int | 患者ctDNA长度 |
-    | cpg | int | 患者甲基化位点数 |
-    | token | string(header) | 请求token，必须提供 |
+    | 参数 | 值类型 | 可空 | 说明 |
+    | --- | --- | --- | --- | 
+    | pid | string | false | 患者数据id |
+    | ctdna | int | false | 患者ctDNA长度 |
+    | cpg | int | false | 患者甲基化位点数 |
+    | token | string(header) | false |请求token，必须提供 |

    例如：
    ``` json
@ -162,7 +164,7 @@

 - 返回数据
  
-    | 字段 | 值类型 | 说明 |
+    | 参数 | 值类型 | 说明 |
    | --- | --- | --- | 
    | id | string | 本次计算请求的任务id |

@ -197,13 +199,13 @@

 - 请求参数：

-    | 参数 | 值类型 | 说明 |
-    | --- | --- | --- | 
-    | uid | string(url) | 需要获取记录的用户uid |
-    | offset | int(url) | 分页数据偏移量 |
-    | limit | int(url) | 每页数据数量 |
-    | page | int(url) | 分页页码 |
-    | token | string(header) | 请求token，必须提供 |
+    | 参数 | 值类型 | 可空 | 说明 |
+    | --- | --- | --- | --- | 
+    | uid | string(url) | false | 需要获取记录的用户uid |
+    | offset | int(url) | false | 分页数据偏移量 |
+    | limit | int(url) | false | 每页数据数量 |
+    | page | int(url) | false | 分页页码 |
+    | token | string(header) | false | 请求token，必须提供 |

    例如，需要获取用户uid为`9a6d777c-997d-a7e5-35f4-8471b7582ac0`记录的第三页数据，每页10条数据：
    ``` 
@ -214,8 +216,8 @@
  
    > data部分以数组的形式返回

-    | 字段 | 值类型 | 说明 |
-    | --- | --- | --- | 
+    | 参数 | 值类型 | 可空 | 说明 |
+    | --- | --- | --- | --- | 
    | id | int | 数据id |
    | pid | int | 患者id |
    | ctdna | int | 患者ctDNA长度 |
@ -269,10 +271,10 @@

 - 请求参数：

-    | 参数 | 值类型 | 说明 |
-    | --- | --- | --- | 
-    | rid | int(url) | 欲删除的计算历史记录 |
-    | token | string(header) | 当前登录用户的token |
+    | 参数 | 值类型 | 可空 | 说明 |
+    | --- | --- | --- | --- | 
+    | rid | int(url) | false | 欲删除的计算历史记录 |
+    | token | string(header) | false |当前登录用户的token |

    例如，需要获取id为`1145`的记录：
    ``` 
@ -292,7 +294,6 @@
    }
    ```

-
 - 错误信息

    | code | 错误 |
@ -308,10 +309,10 @@

 - 请求参数：

-    | 参数 | 值类型 | 说明 |
-    | --- | --- | --- | 
-    | tid | string | 计算任务的id |
-    | token | string(header) | 当前登录用户的token |
+    | 参数 | 值类型 | 可空 | 说明 |
+    | --- | --- | --- | --- | 
+    | tid | string | false | 计算任务的id |
+    | token | string(header) | false | 当前登录用户的token |

    例如：
    ``` 
@ -320,7 +321,7 @@

 - 返回数据
  
-    | 字段 | 值类型 | 说明 |
+    | 参数 | 值类型 | 说明 |
    | --- | --- | --- | 
    | id | string | 本次计算请求的任务id |
    | status | int | 计算状态，0：完成，1：计算中，3：排队中，4：已被终止或未被运行 |
@ -347,9 +348,57 @@

 ## 3. 用户管理相关

+> 这部分的的大部分接口只能由管理员调用使用
+
 ### 添加用户

-> 该项与注册接口相同
+- URL路径：`/user/admin/add`
+- 方法：`POST`
+
+- 请求参数：
+
+    | 参数 | 值类型 | 可空 | 说明 |
+    | --- | --- | --- | --- | 
+    | userName | string | false | 用户登录名，非空 |
+    | password | string | false | 用户登录密码，非空，其值为明文密码两次sha256加密 |
+    | role | int | true | 用户角色 |
+    | token | string(header) | 管理员的access_token |
+
+    例如：
+    ``` json
+    {
+        "userName": "admin",
+        "password": "e723fb2ff93afb010960ac20c05439f1cdd1ecbb533947e7de9f43656a612052",
+        "role": 0
+    }
+    ```
+
+- 返回数据
+  
+    | 字段 | 值类型 | 说明 |
+    | --- | --- | --- | 
+    | uid | string | 用户对应的uid |
+    | role | int | 用户权限类型，0：普通用户，1：管理员 |
+
+
+    例如：
+    ``` json
+    {
+        "code": 20000,
+        "msg": "success",
+        "data" : {
+            "uid": "9a6d777c-997d-a7e5-35f4-8471b7582ac0",
+            "role": 0
+        }
+    }
+    ```
+
+- 错误信息
+
+    | code | 错误 |
+    | --- | --- |
+    | 40300 | 权限不足 |
+    | 20001 | 用户已存在 |

 ---

@ -362,12 +411,12 @@

 - 请求参数：

-    | 参数 | 值类型 | 说明 |
-    | --- | --- | --- | 
-    | uid | string(url) | 欲修改密码的用户uid |
-    | old_password | string | 原始密码，其值为明文密码两次sha256加密，若不提供，则token拥有者应当为管理员 |
-    | new_password | string | 新密码，其值为明文密码两次sha256加密 |
-    | token | string(header) | 当前对应用户的uid |
+    | 参数 | 值类型 | 可空 | 说明 |
+    | --- | --- | --- | --- | 
+    | uid | string(url) | false |欲修改密码的用户uid |
+    | old_password | string | true |原始密码，其值为明文密码两次sha256加密，若不提供，则token拥有者应当为管理员 |
+    | new_password | string | false | 新密码，其值为明文密码两次sha256加密 |
+    | token | string(header) | false | 当前对应用户的uid |

    例如：
    ``` json
@ -400,15 +449,15 @@

 ### 封禁、删除用户

- URL路径：`/user/modifyStatus/{uid}`
+- URL路径：`/user/admin/modifyStatus/{uid}`
 - 方法：`POST`

 - 请求参数：

-    | 参数 | 值类型 | 说明 |
-    | --- | --- | --- | 
-    | uid | string(url) | 欲修的用户uid |
-    | status | int | 修改状态，0：正常；1：彻底封禁（无法登录）；2：注销（销号）；3：计算封禁 |
+    | 参数 | 值类型 | 可空 | 说明 |
+    | --- | --- | --- | --- | 
+    | uid | string(url) | false | 欲修改状态的用户uid |
+    | status | int | false |修改状态，0：正常；1：彻底封禁（无法登录）；2：注销（销号）；3：计算封禁 |
    | token | string(header) | 当前对应用户的uid |

    例如：
@ -436,4 +485,117 @@

    | code | 错误 |
    | --- | --- |
-    | 40300 | 权限不足 |
+    | 40300 | 权限不足 |
+
+---
+
+### 管理员获取待审批注册用户
+
+- URL路径：`/user/admin/application/query?offset={offset}&limit={limit}&page={page}`
+- 方法：`GET`
+
+- 请求参数：
+
+    | 参数 | 值类型 | 可空 | 说明 |
+    | --- | --- | --- | --- | 
+    | offset | int(url) | false | 分页数据偏移量 |
+    | limit | int(url) | false | 每页数据数量 |
+    | page | int(url) | false | 分页页码 |
+    | token | string(header) | false | 请求token，必须提供 |
+
+    例如，需要第三页数据，每页10条数据：
+    ``` 
+    https://dscape.lensfrex.net/api/v1/user/admin/apply?offset=20&limit=10&page=3
+    ```
+
+- 返回数据
+  
+    > data部分以数组的形式返回
+
+    | 参数 | 值类型 | 可空 | 说明 |
+    | --- | --- | --- | --- | 
+    | id | int | 审批记录id |
+    | uid | string | 待审批用户uid |
+    | name | string | 待审批用户名 |
+    | ip | string | 用户发送审批时的ip |
+    | time | datetime(string) | 申请时间 |
+    
+    例如：
+    ``` json
+    {
+        "code": 20000,
+        "msg": "success",
+        "data" : [
+            {
+                "id": 64888,
+                "pid": 2333,
+                "ctdna": 209,
+                "cpg": 5,
+                "hcc": true,
+                "hcc_infer": true,
+                "time": "2022-07-10 08:00:00"
+            },            
+            {
+                "id": 648888,
+                "pid": 23333,
+                "ctdna": 209,
+                "cpg": 5,
+                "hcc": true,
+                "hcc_infer": true,
+                "time": "2022-07-10 08:00:00"
+            },
+            // ...
+        ]
+    }
+    ```
+
+
+- 错误信息
+
+    | code | 错误 |
+    | --- | --- |
+    | 40300 | 权限不足 |
+
+---
+
+### 审核用户注册
+
+- URL路径：`/user/admin/application/deal/{uid}`
+- 方法：`POST`
+
+- 请求参数：
+
+    | 参数 | 值类型 | 可空 | 说明 |
+    | --- | --- | --- | --- | 
+    | uid | string(url) | false | 处理的用户uid |
+    | idea | boolean | false | 处理意见，true：通过；false：拒绝 |
+    | token | string(header) | 当前对应用户的uid |
+
+    例如：
+    ``` json
+    {
+        "uid": "9a6d777c-997d-a7e5-35f4-8471b7582ac0",
+        "idea": true
+    }
+    ```
+
+- 返回数据
+  
+    > data部分无返回数据
+
+    例如：
+    ``` json
+    {
+        "code": 20000,
+        "msg": "success",
+        "data" : null
+    }
+    ```
+
+- 错误信息
+
+    | code | 错误 |
+    | --- | --- |
+    | 40300 | 权限不足 |
+
+---