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

281 lines
5.9 KiB
Plaintext
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

视频观看模块接口文档
=================
基础信息
-------
- 基础路径: /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分钟