API 接口设计
接口地址
环境 | URL |
---|---|
开发环境 | http://like.suevily.cn/ |
生产环境 | 待定 |
通用
- 以下接口分为开放接口和私有接口
- 开放接口:无需登录校验即可请求
- 私有接口:需校验登录 token 方可请求
- 以下所有接口 url 都默认自带
/api
前缀 - token 在使用统一身份验证成功登录后会附带到 redirect url 的 query 参数上,前端需自行存储,开发环境的 redirect url 为
http://localhost:8081/#/
- 私有接口请求方法:将 token 附在请求 Headers 中的 Authorization 字段上,value 格式为
Bearer ${token}
(PS: 建议使用 postman 进行接口测试) - 前端在拿到返回数据时务必先检查 code 是否为零,如若不为零,需给用户正确的反馈,回传数据遵循以下格式:
1 | { |
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 | 办公地址 |
- | 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 | 办公地址 | 是 |
- | 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 | 办公地址 | 是 |
- | String | 邮箱地址 | 是 | |
imageUrl | - | String | 导师照片 url | 是 |
teachForm | - | String | 授课形式 | 是 |
teachTopic | - | Array | 该讲师授课专题的数组 | 是 |
- | String | 授课专题 | 是 |
返回参数
参数 | 类型 | 说明 |
---|---|---|
message | String | 修改结果 |
错误代码
code | 说明 |
---|---|
3001 | 指定 id 的老师不存在 |