SRCC/docs/gitee-api-reference.md

# Gitee OpenAPI v5 参考文档

> 在线 Swagger: https://gitee.com/api/v5/swagger
> Base URL: `https://gitee.com/api/v5`

---

## 1. 认证方式

### 1.1 OAuth 2.0

**授权地址：** `https://gitee.com/oauth/authorize`
**Token 地址：** `https://gitee.com/oauth/token`

支持 grant_type：
- `authorization_code` — 授权码模式
- `password` — 密码模式
- `client_credentials` — 客户端模式
- `refresh_token` — 刷新令牌

### 1.2 请求认证

在 Header 中携带：

```
Authorization: Bearer <access_token>
```

或 Query 参数：

```
?access_token=<access_token>
```

---

## 2. 仓库 (Repos)

### 2.1 仓库 CRUD

| 方法 | 路径 | 说明 |
|------|------|------|
| `GET` | `/repos/{owner}/{repo}` | 获取仓库详情 |
| `POST` | `/user/repos` | 创建仓库 |
| `PATCH` | `/repos/{owner}/{repo}` | 更新仓库 |
| `DELETE` | `/repos/{owner}/{repo}` | 删除仓库 |
| `GET` | `/user/repos` | 当前用户仓库列表 |
| `GET` | `/users/{username}/repos` | 指定用户仓库列表 |
| `GET` | `/orgs/{org}/repos` | 组织仓库列表 |

#### 创建仓库

```bash
curl -X POST "https://gitee.com/api/v5/user/repos" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-project",
    "description": "项目描述",
    "private": false,
    "auto_init": true,
    "license": "MIT"
  }'
```

#### 搜索仓库

```bash
curl "https://gitee.com/api/v5/search/repositories?q=springboot&order=desc&page=1&per_page=20"
```

---

### 2.2 分支管理

| 方法 | 路径 | 说明 |
|------|------|------|
| `GET` | `/repos/{owner}/{repo}/branches` | 分支列表 |
| `GET` | `/repos/{owner}/{repo}/branches/{branch}` | 分支详情 |
| `POST` | `/repos/{owner}/{repo}/branches` | 创建分支 |
| `DELETE` | `/repos/{owner}/{repo}/branches/{branch}` | 删除分支 |

```bash
# 创建分支
curl -X POST "https://gitee.com/api/v5/repos/owner/repo/branches" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "branch_name": "feature-xxx",
    "refs": "master"
  }'
```

---

### 2.3 标签 (Tags)

| 方法 | 路径 | 说明 |
|------|------|------|
| `GET` | `/repos/{owner}/{repo}/tags` | 标签列表 |
| `POST` | `/repos/{owner}/{repo}/tags` | 创建标签 |
| `DELETE` | `/repos/{owner}/{repo}/tags/{tag_name}` | 删除标签 |

---

### 2.4 提交 (Commits)

| 方法 | 路径 | 说明 |
|------|------|------|
| `GET` | `/repos/{owner}/{repo}/commits` | 提交列表 |
| `GET` | `/repos/{owner}/{repo}/commits/{sha}` | 单个提交 |
| `GET` | `/repos/{owner}/{repo}/commits/{sha}/diff` | 提交差异 |
| `GET` | `/repos/{owner}/{repo}/compare/{base}...{head}` | 比较两个提交 |

---

### 2.5 文件内容

| 方法 | 路径 | 说明 |
|------|------|------|
| `GET` | `/repos/{owner}/{repo}/contents/{path}` | 获取文件/目录 |
| `POST` | `/repos/{owner}/{repo}/contents/{path}` | 新建文件 |
| `PUT` | `/repos/{owner}/{repo}/contents/{path}` | 更新文件 |
| `DELETE` | `/repos/{owner}/{repo}/contents/{path}` | 删除文件 |

```bash
# 新建文件
curl -X POST "https://gitee.com/api/v5/repos/owner/repo/contents/src/main.go" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "content": "cGFja2FnZSBtYWluCgpmdW5jIG1haW4oKSB7Cn0=",
    "message": "add main.go",
    "branch": "master"
  }'
```

---

### 2.6 Fork

| 方法 | 路径 | 说明 |
|------|------|------|
| `GET` | `/repos/{owner}/{repo}/forks` | Fork 列表 |
| `POST` | `/repos/{owner}/{repo}/forks` | Fork 仓库 |

---

### 2.7 仓库贡献者/协作者

| 方法 | 路径 | 说明 |
|------|------|------|
| `GET` | `/repos/{owner}/{repo}/collaborators` | 协作者列表 |
| `GET` | `/repos/{owner}/{repo}/collaborators/{username}` | 是否协作者 |
| `PUT` | `/repos/{owner}/{repo}/collaborators/{username}` | 添加/更新协作者 |
| `DELETE` | `/repos/{owner}/{repo}/collaborators/{username}` | 移除协作者 |
| `GET` | `/repos/{owner}/{repo}/contributors` | 贡献者列表 |

---

### 2.8 Star / Watch

| 方法 | 路径 | 说明 |
|------|------|------|
| `GET` | `/repos/{owner}/{repo}/stargazers` | Star 用户列表 |
| `PUT` | `/user/starred/{owner}/{repo}` | Star 仓库 |
| `DELETE` | `/user/starred/{owner}/{repo}` | 取消 Star |
| `GET` | `/user/starred` | 我 Star 的仓库 |
| `GET` | `/repos/{owner}/{repo}/subscribers` | 订阅者列表 |
| `PUT` | `/user/subscriptions/{owner}/{repo}` | 订阅仓库 |
| `DELETE` | `/user/subscriptions/{owner}/{repo}` | 取消订阅 |

---

## 3. Pull Request

| 方法 | 路径 | 说明 |
|------|------|------|
| `GET` | `/repos/{owner}/{repo}/pulls` | PR 列表 |
| `POST` | `/repos/{owner}/{repo}/pulls` | 创建 PR |
| `GET` | `/repos/{owner}/{repo}/pulls/{number}` | PR 详情 |
| `PATCH` | `/repos/{owner}/{repo}/pulls/{number}` | 更新 PR |
| `GET` | `/repos/{owner}/{repo}/pulls/{number}/commits` | PR 提交列表 |
| `GET` | `/repos/{owner}/{repo}/pulls/{number}/files` | PR 文件变更 |
| `GET` | `/repos/{owner}/{repo}/pulls/{number}/merge` | 检查是否可合并 |
| `PUT` | `/repos/{owner}/{repo}/pulls/{number}/merge` | 合并 PR |

```bash
# 创建 PR
curl -X POST "https://gitee.com/api/v5/repos/owner/repo/pulls" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "title": "新功能",
    "head": "feature-branch",
    "base": "master",
    "body": "PR 描述信息"
  }'
```

---

## 4. Issues

| 方法 | 路径 | 说明 |
|------|------|------|
| `GET` | `/repos/{owner}/{repo}/issues` | Issue 列表 |
| `POST` | `/repos/{owner}/{repo}/issues` | 创建 Issue |
| `GET` | `/repos/{owner}/{repo}/issues/{number}` | Issue 详情 |
| `PATCH` | `/repos/{owner}/{repo}/issues/{number}` | 更新 Issue |
| `GET` | `/repos/{owner}/{repo}/issues/{number}/comments` | 评论列表 |
| `POST` | `/repos/{owner}/{repo}/issues/{number}/comments` | 创建评论 |

```bash
# 创建 Issue
curl -X POST "https://gitee.com/api/v5/repos/owner/repo/issues" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "title": "Bug 报告",
    "body": "问题描述...",
    "labels": "bug,high-priority"
  }'
```

---

## 5. 用户 (Users)

| 方法 | 路径 | 说明 |
|------|------|------|
| `GET` | `/user` | 当前用户信息 |
| `PATCH` | `/user` | 更新个人信息 |
| `GET` | `/users/{username}` | 指定用户信息 |
| `GET` | `/user/followers` | 我的粉丝列表 |
| `GET` | `/user/following` | 我关注的用户 |
| `PUT` | `/user/following/{username}` | 关注用户 |
| `DELETE` | `/user/following/{username}` | 取消关注 |
| `GET` | `/user/keys` | SSH 公钥列表 |
| `POST` | `/user/keys` | 添加 SSH 公钥 |
| `DELETE` | `/user/keys/{id}` | 删除 SSH 公钥 |

---

## 6. 组织 (Organizations)

| 方法 | 路径 | 说明 |
|------|------|------|
| `GET` | `/user/orgs` | 我的组织列表 |
| `GET` | `/users/{username}/orgs` | 用户组织列表 |
| `GET` | `/orgs/{org}` | 组织详情 |
| `GET` | `/orgs/{org}/members` | 成员列表 |
| `DELETE` | `/orgs/{org}/members/{username}` | 移除成员 |
| `GET` | `/orgs/{org}/repos` | 组织仓库 |

---

## 7. Webhooks

| 方法 | 路径 | 说明 |
|------|------|------|
| `GET` | `/repos/{owner}/{repo}/hooks` | Hook 列表 |
| `POST` | `/repos/{owner}/{repo}/hooks` | 创建 Hook |
| `GET` | `/repos/{owner}/{repo}/hooks/{id}` | Hook 详情 |
| `PATCH` | `/repos/{owner}/{repo}/hooks/{id}` | 更新 Hook |
| `DELETE` | `/repos/{owner}/{repo}/hooks/{id}` | 删除 Hook |
| `POST` | `/repos/{owner}/{repo}/hooks/{id}/tests` | 测试 Hook |

```bash
# 创建 Webhook
curl -X POST "https://gitee.com/api/v5/repos/owner/repo/hooks" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "url": "https://your-server.com/webhook",
    "password": "optional_secret",
    "push_events": true,
    "tag_push_events": true,
    "issues_events": true,
    "merge_requests_events": true,
    "note_events": true
  }'
```

---

## 8. Go SDK 调用示例

```go
package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io"
    "net/http"
)

const (
    GiteeAPIBase = "https://gitee.com/api/v5"
    AccessToken  = "your_access_token"
)

func giteeRequest(method, path string, body map[string]interface{}) ([]byte, error) {
    url := GiteeAPIBase + path

    var reqBody io.Reader
    if body != nil {
        data, _ := json.Marshal(body)
        reqBody = bytes.NewBuffer(data)
    }

    req, _ := http.NewRequest(method, url, reqBody)
    req.Header.Set("Authorization", "Bearer "+AccessToken)
    req.Header.Set("Content-Type", "application/json")

    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        return nil, err
    }
    defer resp.Body.Close()

    return io.ReadAll(resp.Body)
}

func main() {
    // 获取当前用户信息
    data, _ := giteeRequest("GET", "/user", nil)
    fmt.Println(string(data))

    // 创建 Issue
    data, _ = giteeRequest("POST", "/repos/owner/repo/issues", map[string]interface{}{
        "title": "新 Issue",
        "body":  "通过 API 创建",
    })
    fmt.Println(string(data))
}
```

---

## 9. 仓库参考

| 资源 | 地址 |
|------|------|
| Swagger UI | https://gitee.com/api/v5/swagger |
| OAuth 文档 | https://gitee.com/api/v5/oauth_doc |
| 帮助中心 | https://gitee.com/help |