3分钟上手EasyDarwin API：从文档生成到接口调试全攻略
项目地址: https://gitcode.com/gh_mirrors/ea/EasyDarwin EasyDarwin作为高性能RTSP流媒体服务器，提供了完善的RESTful API接口体系，支持用户认证、直播管理、设备控制等核心功能。本文将详解如何通过项目内置的交互式API文档高效使用这些接口，解决流媒体服务集成中的接口调试痛点。
API文档体系概览
EasyDarwin采用Apifox格式维护API文档，提供了HTML静态文档和JSON规范定义两种形式，满足不同场景的使用需求：
- 交互式HTML文档：doc/EasyDarwin.api.html提供可视化界面，支持接口测试和参数校验
- API规范定义：doc/EasyDarwin.apifox.json包含完整接口元数据，可导入Apifox或Postman使用
- Web端接口文档：部署后可通过web/apidoc.html访问在线版本
文档涵盖用户管理、直播控制、设备配置等6大模块，共计32个核心接口，完整接口清单可查看API定义文件的items数组结构。
快速启动与访问文档
本地部署文档服务
通过项目部署脚本可快速启动包含API文档的Web服务：
-
执行部署目录下的启动脚本：
cd deploy && ./start.sh # Linux/Mac环境 # 或 cd deploy && start.bat # Windows环境 -
访问Web管理界面中的API文档： 打开浏览器访问
http://localhost:10008/apidoc.html，进入文档界面。
文档界面导览
API文档界面采用左侧导航+右侧详情的布局，主要包含三个功能区域：
核心接口实战示例
1. 用户认证接口
所有需要权限的接口均需通过Bearer Token认证，获取令牌的登录接口定义如下：
请求信息：
- 方法：POST
- 路径：
/api/v1/login - 请求体：
{ "username": "admin", "password": "8c6976e5b5410415bde908bd4dee15dfb167a9c873fc4bb8a81f6f2ab448a918" }
密码需经SHA256加密，默认管理员密码"admin"加密后为上述值
响应示例：
{
"id": 222,
"username": "admin",
"name": "系统管理员",
"role": "admin",
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
2. 直播列表查询
获取当前所有直播流信息的分页查询接口：
请求信息：
- 方法：GET
- 路径：
/api/v1/live - 查询参数：
page: 页码(必填)size: 每页条数(必填)type: 直播类型(可选，pull/push)
调用示例：
curl -X GET "http://localhost:10008/api/v1/live?page=1&size=10" \
-H "Authorization: Bearer {your_token}"
响应将返回直播流列表及总数：
{
"items": [
{
"id": 1,
"name": "camera_01",
"url": "rtmp://127.0.0.1:21935/live/stream_1",
"liveType": "push",
"online": 1
}
],
"total": 1
}
3. 直播播放地址获取
获取指定直播ID的播放URL：
请求信息：
- 方法：GET
- 路径：
/api/v1/live/playurl/{id} - 路径参数：
id为直播流ID
响应示例：
{
"rtsp": "rtsp://127.0.0.1:554/stream/1",
"hls": "http://127.0.0.1:8080/hls/stream_1.m3u8",
"webrtc": "wss://127.0.0.1:8443/webrtc/stream_1"
}
高级使用技巧
接口版本控制
API采用URL路径版本控制，当前最新版本为v1，所有接口路径均以/api/v1/开头。版本升级时会通过增加v2、v3等路径进行兼容处理，历史版本接口可在文档中查看。
批量接口调用
对于需要批量操作的场景，可结合utils/pkg/xhttp/工具包中的批量请求方法，示例代码：
import (
"github.com/ea/EasyDarwin/utils/pkg/xhttp"
)
func batchStopStreams(ids []int) error {
client := xhttp.NewClient()
for _, id := range ids {
_, err := client.Post("/api/v1/live/stop", map[string]int{"id": id})
if err != nil {
return err
}
}
return nil
}
接口监控与日志
所有API调用记录可通过plugin/log/模块进行审计，日志文件位于logs/api-access.log，包含请求IP、路径、耗时等信息。
常见问题排查
认证失败处理
若收到401或403响应，可能原因及解决方法：
- Token过期：重新调用登录接口获取新Token
- 权限不足：使用管理员账号登录或联系系统管理员提升权限
- Token格式错误：检查请求头格式是否为
Authorization: Bearer {token}
接口调试工具推荐
除文档内置调试功能外，还可使用以下工具：
- Postman：导入doc/EasyDarwin.apifox.json文件获取完整接口集合
- curl命令：适合脚本化测试，如直播状态检查脚本
- Apifox客户端：支持更复杂的场景测试和接口自动化
总结与资源
通过本文介绍的API文档使用方法，可快速掌握EasyDarwin接口体系。完整接口定义及详细参数说明请查阅：
- 官方API文档：doc/EasyDarwin.api.html
- API规范文件：doc/EasyDarwin.apifox.json
- Web前端API调用：web-src/src/api/目录下的请求封装
建议收藏文档地址，开发过程中随时查阅。如需扩展API功能，可参考internal/web/api/目录下的接口实现代码进行二次开发。
提示：定期查看版本更新日志，获取接口新增及变更信息。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
