更新api文档

main
lensfrex 2 years ago
parent 57e1567977
commit 9b92a98749
Signed by: lensfrex
GPG Key ID: 0F69A0A2FBEE98A0
  1. 282
      API-Document.md

@ -19,7 +19,8 @@
| code | 信息 | | code | 信息 |
| --- | --- | | --- | --- |
| 20000 | 成功 | | 20000 | 成功 |
| 30000 | 参数错误 | 30000 | 参数错误 |
| 30001 | token过期 |
| 40300 | 权限不足 | | 40300 | 权限不足 |
| 40000 | 非法请求 | | 40000 | 非法请求 |
| 50000 | 服务器内部错误 | | 50000 | 服务器内部错误 |
@ -35,10 +36,10 @@
- 请求参数: - 请求参数:
| 参数 | 值类型 | 说明 | | 参数 | 值类型 | 可空 | 说明 |
| --- | --- | --- | | --- | --- | --- | --- |
| userName | string | 用户登录名,非空 | | userName | string | false |用户登录名,非空 |
| password | string | 用户登录密码,非空,其值为明文密码两次sha256加密 | | password | string | false |用户登录密码,非空,其值为明文密码两次sha256加密 |
例如: 例如:
``` json ``` json
@ -50,7 +51,7 @@
- 返回数据 - 返回数据
| 字段 | 值类型 | 说明 | | 参数 | 值类型 | 说明 |
| --- | --- | --- | | --- | --- | --- |
| uid | string | 用户对应的uid | | uid | string | 用户对应的uid |
| role | int | 用户权限类型,0:普通用户,1:管理员 | | role | int | 用户权限类型,0:普通用户,1:管理员 |
@ -78,43 +79,41 @@
| --- | --- | | --- | --- |
| 40301 | 用户名或密码错误 | | 40301 | 用户名或密码错误 |
| 40302 | 用户已被封禁 | | 40302 | 用户已被封禁 |
| 40305 | 上级管理员未认证该用户 |
--- ---
### 用户注册 ### 用户注册(公共)
> 普通用户并不提供注册功能,只能由管理员添加 > 用户注册可由管理员手动创建,也可以由用户自行注册,但是需要提供管理员名称,并且由管理员确认信息后才能使用
> >
> 在系统中首次注册的用户即为管理员,管理员注册后注册接口将不会处理任何非管理员请求,只能由管理员用户请求 > 在系统中首次注册的用户即为管理员,管理员注册后普通用户必须要提供上级管理员才能注册
- URL路径:`/user/register` - URL路径:`/user/register`
- 方法:`POST` - 方法:`POST`
- 请求参数: - 请求参数:
| 参数 | 值类型 | 说明 | | 参数 | 值类型 | 可空 | 说明 |
| --- | --- | --- | | --- | --- | --- | --- |
| userName | string | 用户登录名,非空 | | userName | string | false | 用户登录名,非空 |
| password | string | 用户登录密码,非空,其值为明文密码两次sha256加密 | | password | string | false | 用户登录密码,非空,其值为明文密码两次sha256加密 |
| role | int | 用户角色,该选项只能由管理员使用,其他用户提供不生效 | | superior | string | true | 上级管理员用户名 |
| token | string(header) | 管理员的access_token,如不提供且已经有初始管理员则会导致请求失败(权限不足) |
例如: 例如:
``` json ``` json
{ {
"userName": "admin", "userName": "admin",
"password": "e723fb2ff93afb010960ac20c05439f1cdd1ecbb533947e7de9f43656a612052", "password": "e723fb2ff93afb010960ac20c05439f1cdd1ecbb533947e7de9f43656a612052",
"role": 0 "superior": "lensfrex"
} }
``` ```
- 返回数据 - 返回数据
| 字段 | 值类型 | 说明 | | 参数 | 值类型 | 说明 |
| --- | --- | --- | | --- | --- | --- |
| uid | string | 用户对应的uid | | uid | string | 用户对应的uid |
| role | int | 用户权限类型,0:普通用户,1:管理员 |
例如: 例如:
``` json ``` json
@ -122,16 +121,19 @@
"code": 20000, "code": 20000,
"msg": "success", "msg": "success",
"data" : { "data" : {
"uid": "9a6d777c-997d-a7e5-35f4-8471b7582ac0", "uid": "9a6d777c-997d-a7e5-35f4-8471b7582ac0"
"role": 0
} }
} }
``` ```
- 错误信息 - 错误信息
| code | 错误 | | code | 错误 |
| --- | --- | | --- | --- |
| 40300 | 权限不足 | | 40300 | 权限不足 |
| 20001 | 用户已存在 |
> 管理员添加用户,详见[添加用户](#添加用户)
--- ---
@ -144,12 +146,12 @@
- 请求参数: - 请求参数:
| 参数 | 值类型 | 说明 | | 参数 | 值类型 | 可空 | 说明 |
| --- | --- | --- | | --- | --- | --- | --- |
| pid | string | 患者数据id | | pid | string | false | 患者数据id |
| ctdna | int | 患者ctDNA长度 | | ctdna | int | false | 患者ctDNA长度 |
| cpg | int | 患者甲基化位点数 | | cpg | int | false | 患者甲基化位点数 |
| token | string(header) | 请求token,必须提供 | | token | string(header) | false |请求token,必须提供 |
例如: 例如:
``` json ``` json
@ -162,7 +164,7 @@
- 返回数据 - 返回数据
| 字段 | 值类型 | 说明 | | 参数 | 值类型 | 说明 |
| --- | --- | --- | | --- | --- | --- |
| id | string | 本次计算请求的任务id | | id | string | 本次计算请求的任务id |
@ -197,13 +199,13 @@
- 请求参数: - 请求参数:
| 参数 | 值类型 | 说明 | | 参数 | 值类型 | 可空 | 说明 |
| --- | --- | --- | | --- | --- | --- | --- |
| uid | string(url) | 需要获取记录的用户uid | | uid | string(url) | false | 需要获取记录的用户uid |
| offset | int(url) | 分页数据偏移量 | | offset | int(url) | false | 分页数据偏移量 |
| limit | int(url) | 每页数据数量 | | limit | int(url) | false | 每页数据数量 |
| page | int(url) | 分页页码 | | page | int(url) | false | 分页页码 |
| token | string(header) | 请求token,必须提供 | | token | string(header) | false | 请求token,必须提供 |
例如,需要获取用户uid为`9a6d777c-997d-a7e5-35f4-8471b7582ac0`记录的第三页数据,每页10条数据: 例如,需要获取用户uid为`9a6d777c-997d-a7e5-35f4-8471b7582ac0`记录的第三页数据,每页10条数据:
``` ```
@ -214,8 +216,8 @@
> data部分以数组的形式返回 > data部分以数组的形式返回
| 字段 | 值类型 | 说明 | | 参数 | 值类型 | 可空 | 说明 |
| --- | --- | --- | | --- | --- | --- | --- |
| id | int | 数据id | | id | int | 数据id |
| pid | int | 患者id | | pid | int | 患者id |
| ctdna | int | 患者ctDNA长度 | | ctdna | int | 患者ctDNA长度 |
@ -269,10 +271,10 @@
- 请求参数: - 请求参数:
| 参数 | 值类型 | 说明 | | 参数 | 值类型 | 可空 | 说明 |
| --- | --- | --- | | --- | --- | --- | --- |
| rid | int(url) | 欲删除的计算历史记录 | | rid | int(url) | false | 欲删除的计算历史记录 |
| token | string(header) | 当前登录用户的token | | token | string(header) | false |当前登录用户的token |
例如,需要获取id为`1145`的记录: 例如,需要获取id为`1145`的记录:
``` ```
@ -292,7 +294,6 @@
} }
``` ```
- 错误信息 - 错误信息
| code | 错误 | | code | 错误 |
@ -308,10 +309,10 @@
- 请求参数: - 请求参数:
| 参数 | 值类型 | 说明 | | 参数 | 值类型 | 可空 | 说明 |
| --- | --- | --- | | --- | --- | --- | --- |
| tid | string | 计算任务的id | | tid | string | false | 计算任务的id |
| token | string(header) | 当前登录用户的token | | token | string(header) | false | 当前登录用户的token |
例如: 例如:
``` ```
@ -320,7 +321,7 @@
- 返回数据 - 返回数据
| 字段 | 值类型 | 说明 | | 参数 | 值类型 | 说明 |
| --- | --- | --- | | --- | --- | --- |
| id | string | 本次计算请求的任务id | | id | string | 本次计算请求的任务id |
| status | int | 计算状态,0:完成,1:计算中,3:排队中,4:已被终止或未被运行 | | status | int | 计算状态,0:完成,1:计算中,3:排队中,4:已被终止或未被运行 |
@ -347,9 +348,57 @@
## 3. 用户管理相关 ## 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 | | uid | string(url) | false |欲修改密码的用户uid |
| old_password | string | 原始密码,其值为明文密码两次sha256加密,若不提供,则token拥有者应当为管理员 | | old_password | string | true |原始密码,其值为明文密码两次sha256加密,若不提供,则token拥有者应当为管理员 |
| new_password | string | 新密码,其值为明文密码两次sha256加密 | | new_password | string | false | 新密码,其值为明文密码两次sha256加密 |
| token | string(header) | 当前对应用户的uid | | token | string(header) | false | 当前对应用户的uid |
例如: 例如:
``` json ``` json
@ -400,15 +449,15 @@
### 封禁、删除用户 ### 封禁、删除用户
- URL路径:`/user/modifyStatus/{uid}` - URL路径:`/user/admin/modifyStatus/{uid}`
- 方法:`POST` - 方法:`POST`
- 请求参数: - 请求参数:
| 参数 | 值类型 | 说明 | | 参数 | 值类型 | 可空 | 说明 |
| --- | --- | --- | | --- | --- | --- | --- |
| uid | string(url) | 欲修的用户uid | | uid | string(url) | false | 欲修改状态的用户uid |
| status | int | 修改状态,0:正常;1:彻底封禁(无法登录);2:注销(销号);3:计算封禁 | | status | int | false |修改状态,0:正常;1:彻底封禁(无法登录);2:注销(销号);3:计算封禁 |
| token | string(header) | 当前对应用户的uid | | token | string(header) | 当前对应用户的uid |
例如: 例如:
@ -436,4 +485,117 @@
| code | 错误 | | 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 | 权限不足 |
---

Loading…
Cancel
Save