API接口设计

API 接口设计

接口地址

环境 URL
开发环境 http://like.suevily.cn/
生产环境 待定

通用

  1. 以下接口分为开放接口和私有接口
    • 开放接口:无需登录校验即可请求
    • 私有接口:需校验登录 token 方可请求
  2. 以下所有接口 url 都默认自带 /api 前缀
  3. token 在使用统一身份验证成功登录后会附带到 redirect url 的 query 参数上,前端需自行存储,开发环境的 redirect url 为 http://localhost:8081/#/
  4. 私有接口请求方法:将 token 附在请求 Headers 中的 Authorization 字段上,value 格式为 Bearer ${token} (PS: 建议使用 postman 进行接口测试)
  5. 前端在拿到返回数据时务必先检查 code 是否为零,如若不为零,需给用户正确的反馈,回传数据遵循以下格式:
1
2
3
4
{
code: Number,
data: Object
}
code 说明
0 成功
-1 未知错误,查看 message
1 拒绝访问
2 无效的请求参数
3 上传图片出错
4 token 校验失败
其它 待定

获取用户信息

method url type
GET /user 私有接口

请求参数

返回参数

参数 类型 说明
cardId String 校园卡号
name String 姓名
college String 学院
stuId String 学号
privilege Number 0 为超级管理员,1为普通管理员,如没有该字段则为普通师生

获取管理人员

method url type
POST /getManagers 私有接口

请求参数

参数 类型 说明 必填
perPage Number 每页包含元素个数
page Number 页码,第几页

返回参数

参数 字段 类型 说明
length - Number 管理人员总数
managers - Array 一个包含指定页数内所有管理人员的数组
- id Number 该管理员在数据库中的唯一标识
- name String 姓名
- cardId String 校园卡号
- authorizer String 授权人姓名
- createdAt Date 添加时间戳
- privilege String 管理权限,超级管理员或普通管理员

添加管理人员

method url type
POST /addManager 私有接口

请求参数

参数 类型 说明 必填
name String 姓名
cardId String 校园卡号
privilege Number 权限,0 为超级管理员,1为普通管理员

返回参数

参数 类型 说明
message String 添加结果

错误代码

code 说明
1001 校园卡号冲突

修改管理人员

method url type
POST /updateManager 私有接口

请求参数

参数 类型 说明 必填
id Number 要修改的管理员的id
name String 姓名
cardId String 校园卡号
privilege Number 权限,0 为超级管理员,1为普通管理员

返回参数

参数 类型 说明
message String 修改结果

错误代码

code 说明
1002 当你要把最后一个超级管理员更改为普通管理员时会出错

删除管理人员

method url type
POST /deleteManager 私有接口

请求参数

参数 类型 说明 必填
id String 要删除的管理员的id

返回参数

参数 类型 说明
message String 删除结果

错误代码

code 说明
1003 当你要把最后一个超级管理员删除时会出错

搜索管理人员

method url type
POST /searchManagers 私有接口

请求参数

参数 类型 说明 必填
keyword String 搜索关键词
maxLength Number 搜索结果最大返回数目(默认为5)

返回参数

参数 字段 类型 说明
managers - Array 满足搜索关键词的管理员数组
- id Number 该管理员在数据库中的唯一标识
- name String 姓名
- cardId String 校园卡号
- authorizer String 授权人姓名
- createdAt Date 添加时间戳
- privilege String 管理权限,超级管理员或普通管理员

获取课程信息

method url type
POST /getCourses 私有接口

请求参数

参数 类型 说明 必填
perPage Number 每页包含元素个数
page Number 页码,第几页

返回参数

参数 字段 类型 说明
length - Number 课程总数
courses - Array 一个包含指定页数所有课程信息的数组
- courseName String 课程名称
- teacher String 讲师姓名
time String 上课时间,前端直接展示即可
courseId String 课程编号
location String 上课地点
studentCount Number 选课人数

根据课程编号获取课程详细信息

method url type
POST /getCourseInfo 私有接口

请求参数

参数 类型 说明 必填
courseId String 课程编号

返回参数

参数 字段 类型 说明
courseName - String 课程名称
teacherId - String 讲师在数据库中的id
teacherName - String 讲师姓名
startTime - Date 上课开始时间戳
endTime - Date 上课结束时间戳
location - String 上课地点
students - Array 一个包含指定课程选课所有学生信息的数组
name String 学生姓名
stuId String 学生学号

错误代码

code 说明
2003 课程编号错误

查询选课名单

method url type
POST /getStudentList 私有接口

请求参数

参数 类型 说明 必填
courseId String 课程编号
perPage Number 每页包含元素个数
page Number 页码,第几页

返回参数

参数 字段 类型 说明
length - Number 选课总人数
students - Array 一个包含指定课程选课所有学生信息的数组
name String 学生姓名
stuId String 学生学号

删除课程

method url type
POST /deleteCourse 私有接口

请求参数

参数 类型 说明 必填
courseId String 要删除的课程的课程编号

返回参数

参数 类型 说明
message String 删除结果

搜索课程

method url type
POST /searchCourses 私有接口

请求参数

参数 类型 说明 必填
keyword String 搜索关键词
maxLength Number 搜索结果最大返回数目(默认为5)

返回参数

参数 字段 类型 说明
courses - Array 满足搜索关键词的课程数组
- courseName String 课程名称
- teacher String 讲师姓名
time String 上课时间,前端直接展示即可
courseId String 课程编号
location String 上课地点
studentCount Number 选课人数

生成课程

method url type
POST /addCourse 私有接口

请求参数

参数 字段 类型 说明 必填
courseName - String 课程名称
teacherId - String 讲师在数据库中的id
startTime - Date 上课开始时间戳
endTime - Date 上课结束时间戳
location - String 上课地点
students - Array 选课学生数组
- name String 学生姓名
- stuId String 学生学号

返回参数

参数 类型 说明
courseId String 生成的课程编号

错误代码

code 说明
2001 讲师不存在

修改课程

method url type
POST /updateCourse 私有接口

请求参数

参数 字段 类型 说明 必填
courseId - String 课程编号(乱传打爆你▄︻┻═┳一)
courseName - String 课程名称
teacherId - String 讲师在数据库中的id
startTime - String 上课开始时间戳
endTime - String 上课结束时间戳
location - String 上课地点
students - Array 选课学生数组
- name String 学生姓名
- stuId String 学生学号

返回参数

参数 类型 说明
message String 修改结果

错误代码

code 说明
2001 讲师不存在
2002 课程编号不存在

获取讲师信息

method url type
POST /getTeachers 私有接口

请求参数

参数 类型 说明 必填
perPage Number 每页包含元素个数
page Number 页码,第几页

返回参数

参数 字段 类型 说明
length - Number 讲师总数
teachers - Array 一个包含指定页数所有讲师信息的数组
- id Number 该讲师在数据库的唯一标识
- name String 讲师姓名
imageUrl String 讲师照片的 url

删除讲师

method url type
POST /deleteTeacher 私有接口

请求参数

参数 类型 说明 必填
id Number 讲师 id ,在 /getTeachers 接口获取到的

返回参数

参数 类型 说明
message String 删除结果

搜索讲师

method url type
POST /searchTeachers 私有接口

请求参数

参数 类型 说明 必填
keyword String 搜索关键词
maxLength Number 搜索结果最大返回数目(默认为5)

返回参数

参数 字段 类型 说明
teachers - Array 满足搜索关键字的讲师数组
id Number 该讲师在数据库的唯一标识
- name String 讲师姓名
imageUrl String 讲师照片的 url

查询一个讲师的详细信息

method url type
POST /getTeacherInfo 私有接口

请求参数

参数 类型 说明 必填
id Number 讲师 id ,在 /getTeachers 接口获取到的

返回参数

参数 字段 类型 说明
name - String 讲师姓名
college - String 所属单位
intro - String 老师简介
phone - String 手机号码
office - String 办公地址
email - String 邮箱地址
imageUrl - String 导师照片 url
teachForm - String 授课形式
teachTopic - Array 该讲师授课专题的数组
- String 授课专题

图片上传接口

method url type
POST /upload 私有接口

请求参数

参数 类型 说明 必填
- FormData 图片数据

返回参数

参数 类型 说明
url String 图片 url

添加讲师

method url type
POST /addTeacher 私有接口

请求参数

参数 字段 类型 说明 必填
name - String 讲师姓名
college - String 所属单位
intro - String 老师简介
phone - String 手机号码
office - String 办公地址
email - String 邮箱地址
imageUrl - String 导师照片 url
teachForm - String 授课形式
teachTopic - Array 该讲师授课专题的数组
- String 授课专题

返回参数

参数 类型 说明
id Number 该讲师在数据库的唯一标识

修改讲师信息

method url type
POST /updateTeacher 私有接口

请求参数

参数 字段 类型 说明 必填
id - Number 要修改的讲师的 id
name - String 讲师姓名
college - String 所属单位
intro - String 老师简介
phone - String 手机号码
office - String 办公地址
email - String 邮箱地址
imageUrl - String 导师照片 url
teachForm - String 授课形式
teachTopic - Array 该讲师授课专题的数组
- String 授课专题

返回参数

参数 类型 说明
message String 修改结果

错误代码

code 说明
3001 指定 id 的老师不存在