76 lines
1.9 KiB
Markdown
76 lines
1.9 KiB
Markdown
# GitLink API 参考
|
||
|
||
## 认证端点
|
||
|
||
| 端点 | 方法 | 说明 |
|
||
|------|------|------|
|
||
| `/accounts/login` | POST | 用户名密码登录 |
|
||
| `/users/me` | GET | 获取当前用户信息 |
|
||
|
||
## 全局参数
|
||
|
||
| 参数 | 位置 | 说明 |
|
||
|------|------|------|
|
||
| `access_token` | Query | OAuth2 Token（自动注入） |
|
||
| `page` | Query | 分页页码（默认 1） |
|
||
| `limit` | Query | 每页条数（默认 20） |
|
||
|
||
## 响应格式
|
||
|
||
**成功响应**:
|
||
```json
|
||
{
|
||
"ok": true,
|
||
"data": { ... },
|
||
"meta": { "page": 1, "limit": 20, "total_count": 100 }
|
||
}
|
||
```
|
||
|
||
**错误响应**:
|
||
```json
|
||
{
|
||
"ok": false,
|
||
"error": {
|
||
"code": 401,
|
||
"message": "无效token",
|
||
"suggestion": "请先运行 gitlink-cli auth login 登录"
|
||
}
|
||
}
|
||
```
|
||
|
||
## 常见错误码
|
||
|
||
| 错误码 | 含义 | 解决方案 |
|
||
|--------|------|----------|
|
||
| 401 | 未认证 | 运行 `gitlink-cli auth login` |
|
||
| 403 | 权限不足 | 确认账户权限或联系项目管理员 |
|
||
| 404 | 资源不存在 | 检查 owner/repo/id 是否正确 |
|
||
| 422 | 参数校验失败 | 检查请求参数 |
|
||
| -1 | GitLink 业务错误 | 查看 message 字段获取详情 |
|
||
|
||
## API 特殊性
|
||
|
||
### 必需字段
|
||
|
||
| 操作 | 必需字段 | 说明 |
|
||
|------|----------|------|
|
||
| Issue 创建 | `done_ratio: 0` | 数据库约束 |
|
||
| Issue 更新 | 当前 `subject` 和 `description` | 即使只改状态也应保留，避免清空描述 |
|
||
| Release 查看 | `version_id` | 不能用 tag_name |
|
||
|
||
### 端点前缀
|
||
|
||
| 操作 | 前缀 | 示例 |
|
||
|------|------|------|
|
||
| 分支操作 | `/v1/` | `/v1/:owner/:repo/branches` |
|
||
| Issue 评论 | 无 | `/issues/:id/journals` |
|
||
| 仓库操作 | 无 | `/:owner/:repo/info` |
|
||
|
||
### 已知 Bug
|
||
|
||
| Bug | 影响 | 状态 |
|
||
|-----|------|------|
|
||
| Branch 删除返回"不存在" | 无法删除分支 | 待 GitLink 修复 |
|
||
| Release 删除返回"不存在" | 无法删除发布 | 待 GitLink 修复 |
|
||
| Create File 返回"已存在" | 无法通过 API 创建文件 | 待 GitLink 修复 |
|