yl-frontend/api-docs/video-api.txt

281 lines
5.9 KiB
Plaintext
Raw Permalink Normal View History

2024-12-05 21:56:49 +08:00
视频观看模块接口文档
=================
基础信息
-------
- 基础路径: /api/v1/videos
- 请求方式: REST
- 数据格式: JSON
- 认证方式: Bearer Token
数据结构
-------
Video 视频对象:
{
id: number, // 视频ID
title: string, // 视频标题
description: string, // 视频描述
url: string, // 视频URL
thumbnail: string, // 缩略图URL
duration: string, // 视频时长
category: string, // 视频分类
views: number, // 观看次数
likes: number, // 点赞数
comments: number, // 评论数
tags: string[], // 标签
uploadTime: string, // 上传时间
status: string // 视频状态(active/disabled)
}
API 接口
-------
1. 获取视频列表
GET /api/v1/videos
请求参数:
| 参数名 | 类型 | 必填 | 说明 |
| category | string | 否 | 视频分类 |
| page | number | 否 | 页码默认1 |
| size | number | 否 | 每页数量默认10 |
| sort | string | 否 | 排序字段(uploadTime/views/likes) |
| order | string | 否 | 排序方式(asc/desc) |
响应示例:
{
"code": 200,
"message": "success",
"data": {
"total": 100,
"pages": 10,
"current": 1,
"records": [
{
"id": 1,
"title": "每日健康操",
"description": "适合老年人的健康运动视频",
"url": "http://example.com/video1.mp4",
"thumbnail": "http://example.com/thumb1.jpg",
"duration": "10:00",
"category": "health",
"views": 1234,
"likes": 256,
"comments": 45,
"tags": ["健康", "运动", "教学"],
"uploadTime": "2024-03-20 10:00:00",
"status": "active"
}
]
}
}
2. 获取视频详情
GET /api/v1/videos/{id}
响应示例:
{
"code": 200,
"message": "success",
"data": {
"id": 1,
"title": "每日健康操",
"description": "适合老年人的健康运动视频",
"url": "http://example.com/video1.mp4",
"thumbnail": "http://example.com/thumb1.jpg",
"duration": "10:00",
"category": "health",
"views": 1234,
"likes": 256,
"comments": 45,
"tags": ["健康", "运动", "教学"],
"uploadTime": "2024-03-20 10:00:00",
"status": "active"
}
}
3. 更新观看次数
POST /api/v1/videos/{id}/view
响应示例:
{
"code": 200,
"message": "success",
"data": {
"views": 1235
}
}
4. 点赞视频
POST /api/v1/videos/{id}/like
响应示例:
{
"code": 200,
"message": "success",
"data": {
"likes": 257
}
}
5. 获取推荐视频
GET /api/v1/videos/recommended
请求参数:
| 参数名 | 类型 | 必填 | 说明 |
| currentId | number | 否 | 当前视频ID |
| limit | number | 否 | 返回数量默认3 |
响应示例:
{
"code": 200,
"message": "success",
"data": [
{
"id": 2,
"title": "太极拳教学",
"description": "专业老师讲解太极拳基本动作",
"url": "http://example.com/video2.mp4",
"thumbnail": "http://example.com/thumb2.jpg",
"duration": "15:00",
"category": "health",
"views": 890,
"likes": 156,
"comments": 23,
"tags": ["太极拳", "运动", "教学"],
"uploadTime": "2024-03-19 15:00:00",
"status": "active"
}
]
}
6. 获取热门视频
GET /api/v1/videos/hot
请求参数:
| 参数名 | 类型 | 必填 | 说明 |
| limit | number | 否 | 返回数量默认5 |
响应示例:
{
"code": 200,
"message": "success",
"data": [
{
"id": 3,
"title": "广场舞教学",
"description": "广场舞基础动作教学",
"url": "http://example.com/video3.mp4",
"thumbnail": "http://example.com/thumb3.jpg",
"duration": "20:00",
"category": "entertainment",
"views": 2345,
"likes": 456,
"comments": 78,
"tags": ["广场舞", "运动", "教学"],
"uploadTime": "2024-03-18 14:00:00",
"status": "active"
}
]
}
7. 获取视频分类
GET /api/v1/videos/categories
响应示例:
{
"code": 200,
"message": "success",
"data": [
{
"value": "health",
"label": "健康讲座",
"count": 25
},
{
"value": "entertainment",
"label": "娱乐节目",
"count": 18
}
]
}
8. 添加视频评论
POST /api/v1/videos/{id}/comments
请求参数:
{
"content": "视频很有帮助",
"parentId": null // 回复其他评论时设置
}
响应示例:
{
"code": 200,
"message": "success",
"data": {
"id": 1,
"content": "视频很有帮助",
"userId": 10001,
"userName": "张三",
"createTime": "2024-03-20 15:30:00",
"parentId": null,
"likes": 0
}
}
9. 获取视频评论列表
GET /api/v1/videos/{id}/comments
请求参数:
| 参数名 | 类型 | 必填 | 说明 |
| page | number | 否 | 页码默认1 |
| size | number | 否 | 每页数量默认10 |
响应示例:
{
"code": 200,
"message": "success",
"data": {
"total": 45,
"pages": 5,
"current": 1,
"records": [
{
"id": 1,
"content": "视频很有帮助",
"userId": 10001,
"userName": "张三",
"createTime": "2024-03-20 15:30:00",
"parentId": null,
"likes": 5,
"replies": []
}
]
}
}
错误码说明
--------
| 错误码 | 说明 |
| 200 | 成功 |
| 400 | 请求参数错误 |
| 401 | 未授权 |
| 403 | 禁止访问 |
| 404 | 资源不存在 |
| 500 | 服务器内部错误 |
注意事项
-------
1. 视频文件上传需要单独处理,建议使用分片上传:
POST /api/v1/videos/upload
Content-Type: multipart/form-data
2. 视频URL需要进行加密和有效期控制防止视频泄露。
3. 视频播放建议使用 HLS 或 DASH 协议,支持多码率自适应。
4. 缓存策略:
- 视频元数据缓存5分钟
- 视频分类缓存1小时
- 热门视频缓存10分钟