记MD写接口文档

发表于 | 更新于: | 分类于 ，
字数统计: 714 | 阅读时长 ≈ 3

记录一次用Md写接口文档

部分改动

根据原有的开发文档，进行改进。具体改动如下：

  • 添加接口版本信息，方便以后版本迭代。
  • 部分接口需要验证权限，如添加用户接口，普通用户无法调用。
  • 登录成功后，返回用户token，token作为后端识别用户的唯一标识。

接口文档

0x01注册接口

  • 路由
    http://www.unisona.net/api/v1/register/
  • 协议
    POST
  • 权限
    无
  • 参数
名称 是否必须 说明
id True 手机号`^1(3
password True 密码[A-Za-z0-9_*&$#@]{6,20}$
  • 返回结果

成功

1
{
2
    "data": {},
3
    "message": "Register success",
4
    "success": true
5
}

失败

1
{
2
    "data": {},
3
    "message": {
4
        "password": [
5
            "密码格式不正确"
6
        ],
7
        "phone": [
8
            "手机号格式不正确"
9
        ]
10
    },
11
    "success": false
12
}

0x02登录接口

  • 路由
    http://www.unisona.net/api/v1/login/
  • 协议
    POST
  • 权限
    无
  • 参数
名称 是否必须 说明
id True 手机号`^1(3
password True 密码[A-Za-z0-9_*&$#@]{6,20}$
  • 返回结果

成功

1
{
2
    "data": {
3
        "token": "eyJhbGciOiJIUzUxMiIsImlhdCI6MTU5NzEyNjM1OCwiZXhwIjoxNTk5NzE4MzU4fQ.eyJ1aWQiOiI1N3lNZWhqYW5wWmZoeGtlZFVGeDZpIiwic2NvcGUiOiJVc2VyU2NvcGUifQ.dHcY3bQY786HnyywXx_uriYHtJApm8kwIzu1ksT6_I6bQ8G38oW_WXcwWcZeGqFaF0RK9qcNDI_BVFsCOC9S2Q"
4
    },
5
    "message": "Login success",
6
    "success": true
7
}

失败

1
{
2
    "data": {},
3
    "message": "账号或者密码错误",
4
    "success": false
5
}

0x03添加用户接口

  • 路由
    http://www.unisona.net/api/v1/adduser/
  • 协议
    POST
  • 权限
    管理员、超级管理员
  • 参数
名称 是否必须 说明
id True 手机号`^1(3
username True 长度不得超过12个字符
gender True (男、女、未知)
age False 正整数
  • 返回结果

成功

1
{
2
    "data": {
3
        "password": "123456"  //默认密码123456
4
    },
5
    "message": "Add user success",
6
    "success": true
7
}

失败

1
{
2
    "data": {},
3
    "message": {
4
        "id": [
5
            "改手机号已经被注册"
6
        ]
7
    },
8
    "success": false
9
}

0x04用户数据接口

  • 路由
    http://www.unisona.net/api/v1/userdata/

  • 协议
    GET

  • 权限
    无

  • 参数

名称 是否必须 说明
id True 手机号`^1(3
  • 返回结果

成功

1
{
2
    "data": {
3
        "user": {
4
            "address": null,
5
            "age": null,
6
            "gender": "未知",
7
            "id": "VP5UuXznkZ8hHaQSBRLtrT",
8
            "persion_id": null,
9
            "phone": "15225090724",
10
            "username": "优超医疗用户"
11
        }
12
    },
13
    "message": "ok",
14
    "success": true
15
}

失败

1
{
2
    "data": {},
3
    "message": "资源不存在",
4
    "success": false
5
}

0x05声音传输接口

  • 路由
    http://www.unisona.net/api/v1/diagnose/

  • 协议
    POST

  • 权限
    普通用户、管理员、超级管理员

  • 参数

名称 是否必须 说明
file True 声音文件,格式目前支持wav,最大2M

返回结果

成功

1
{
2
    "data": {
3
        "result": "true"
4
    },
5
    "message": "ok",
6
    "success": true
7
}

失败

1
{
2
    "data": {},
3
    "message": "文件格式不符合",
4
    "success": false
5
}

注意点

  • 用户登录成功后，token需要前端自己存储，认证类型为Basic Auth直接将token放在username中即可，如下图：

  • 数据库设计存在多个字段，如身份证、用户地址等等，如有需要，可以添加。