docs: 添加 Gitea API 使用文档

记录了三个核心 API： - 获取用户仓库列表 - 创建新仓库 - 上传通用包包含完整的请求示例和响应数据结构。
2026-02-18 01:44:57 +08:00
parent 0c42856cc8
commit 59942acdbb
1 changed files with 260 additions and 0 deletions
--- a/gitea_api.md
+++ b/gitea_api.md
@@ -0,0 +1,260 @@
+# Gitea API 使用文档
+
+## 概述
+
+本文档总结了在本次项目中成功使用的 Gitea API。
+
+**Gitea 地址：** http://gitea.xieyao.vip/
+**用户名：** xieyao
+**Token：** 1ce08e3ca5d94641e0a243f374bba450f7639147
+**API 版本：** v1
+
+---
+
+## 1. 获取用户仓库列表
+
+### 接口信息
+
+- **URL：** `/api/v1/user/repos`
+- **方法：** `GET`
+- **认证：** `Authorization: token <token>`
+
+### 请求示例
+
+```bash
+curl -s -H "Authorization: token 1ce08e3ca5d94641e0a243f374bba450f7639147" \
+  http://gitea.xieyao.vip/api/v1/user/repos
+```
+
+### 响应数据结构
+
+```json
+{
+  "id": 6,
+  "name": "control",
+  "full_name": "xieyao/control",
+  "description": "",
+  "private": true,
+  "language": "Dart",
+  "size": 651,
+  "html_url": "http://192.168.1.6:3000/xieyao/control",
+  "clone_url": "http://192.168.1.6:3000/xieyao/control.git",
+  "ssh_url": "git@192.168.1.6:xieyao/control.git",
+  "default_branch": "main",
+  "created_at": "2026-02-16T15:16:10Z",
+  "updated_at": "2026-02-16T15:18:07Z"
+}
+```
+
+### 关键字段说明
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `id` | number | 仓库 ID |
+| `name` | string | 仓库名称 |
+| `full_name` | string | 完整名称 (owner/name) |
+| `description` | string | 仓库描述 |
+| `private` | boolean | 是否私有 |
+| `language` | string | 主要编程语言 |
+| `size` | number | 仓库大小（字节） |
+| `html_url` | string | 仓库访问地址 |
+| `clone_url` | string | HTTP 克隆地址 |
+| `ssh_url` | string | SSH 克隆地址 |
+| `default_branch` | string | 默认分支 |
+| `created_at` | string | 创建时间 (ISO 8601) |
+| `updated_at` | string | 更新时间 (ISO 8601) |
+
+---
+
+## 2. 创建新仓库
+
+### 接口信息
+
+- **URL：** `/api/v1/user/repos`
+- **方法：** `POST`
+- **认证：** `Authorization: token <token>`
+- **Header：** `Content-Type: application/json`
+
+### 请求示例
+
+```bash
+curl -s -X POST -H "Authorization: token 1ce08e3ca5d94641e0a243f374bba450f7639147" \
+  -H "Content-Type: application/json" \
+  http://gitea.xieyao.vip/api/v1/user/repos \
+  -d '{
+    "name": "message",
+    "description": "汪汪的message仓库",
+    "auto_init": true,
+    "private": false
+  }'
+```
+
+### 请求参数
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `name` | string | 是 | 仓库名称 |
+| `description` | string | 否 | 仓库描述 |
+| `auto_init` | boolean | 否 | 是否自动初始化（创建 README） |
+| `private` | boolean | 否 | 是否私有 |
+
+### 响应示例
+
+```json
+{
+  "id": 9,
+  "name": "message",
+  "full_name": "xieyao/message",
+  "description": "汪汪的message仓库",
+  "private": false,
+  "language": "",
+  "size": 23,
+  "html_url": "http://192.168.1.6:3000/xieyao/message",
+  "clone_url": "http://192.168.1.6:3000/xieyao/message.git",
+  "ssh_url": "git@192.168.1.6:xieyao/message.git",
+  "default_branch": "main",
+  "created_at": "2026-02-17T16:37:59Z",
+  "updated_at": "2026-02-17T16:38:00Z"
+}
+```
+
+---
+
+## 3. 上传通用包（Generic Package Registry）
+
+### 接口信息
+
+- **URL：** `/api/packages/{owner}/generic/{package_name}/{package_version}/{file_name}`
+- **方法：** `PUT`
+- **认证：** `Basic Auth` 或 `token`
+- **Content-Type：** `application/octet-stream`
+
+### 请求示例
+
+```bash
+curl -s -X PUT -u "xieyao:1ce08e3ca5d94641e0a243f374bba450f7639147" \
+  --upload-file devspec \
+  http://gitea.xieyao.vip/api/packages/xieyao/generic/devspec/1.0.0/devspec \
+  -w "\nHTTP Status: %{http_code}\n"
+```
+
+### 参数说明
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `owner` | string | 用户名或组织名 |
+| `package_name` | string | 包名称（只能包含小写字母、数字、点、减号、加号、下划线） |
+| `package_version` | string | 版本号（不能为空，前后不能有空格） |
+| `file_name` | string | 文件名（只能包含小写字母、数字、点、减号、加号、下划线） |
+
+### 响应
+
+**成功：**
+```
+HTTP/2 201
+```
+
+**失败：**
+- `400 Bad Request`：参数无效
+- `409 Conflict`：文件名已存在
+- `401 Unauthorized`：认证失败
+
+### 验证包是否成功上传
+
+```bash
+curl -s -k -u "xieyao:1ce08e3ca5d94641e0a243f374bba450f7639147" \
+  "http://gitea.xieyao.vip/api/packages/xieyao/generic/devspec/1.0.0/devspec" \
+  -o downloaded_file \
+  -w "\nHTTP Status: %{http_code}\n"
+```
+
+---
+
+## 常用工具函数（bash）
+
+### 获取仓库列表
+
+```bash
+get_repos() {
+  curl -s -H "Authorization: token $GITEA_TOKEN" \
+    $GITEA_API_URL/api/v1/user/repos
+}
+```
+
+### 创建仓库
+
+```bash
+create_repo() {
+  local name="$1"
+  local description="${2:-}"
+  local auto_init="${3:-true}"
+  local private="${4:-false}"
+
+  curl -s -X POST -H "Authorization: token $GITEA_TOKEN" \
+    -H "Content-Type: application/json" \
+    $GITEA_API_URL/api/v1/user/repos \
+    -d "{
+      \"name\": \"$name\",
+      \"description\": \"$description\",
+      \"auto_init\": $auto_init,
+      \"private\": $private
+    }"
+}
+```
+
+### 上传通用包
+
+```bash
+upload_generic_package() {
+  local owner="$1"
+  local package_name="$2"
+  local package_version="$3"
+  local file_path="$4"
+
+  curl -s -k -X PUT -u "$GITEA_USERNAME:$GITEA_TOKEN" \
+    --upload-file "$file_path" \
+    "$GITEA_API_URL/api/packages/$owner/generic/$package_name/$package_version/$(basename $file_path)" \
+    -w "\nHTTP Status: %{http_code}\n"
+}
+```
+
+---
+
+## 注意事项
+
+1. **认证方式**
+   - 使用 Token 认证：`Authorization: token <token>`
+   - 使用 Basic Auth：`-u username:token`
+
+2. **HTTPS 证书**
+   - 如果 Gitea 使用自签名证书，需要添加 `-k` 参数跳过验证
+
+3. **包命名规则**
+   - 包名和文件名只能包含小写字母、数字、点、减号、加号、下划线
+   - 版本号不能为空，前后不能有空格
+
+4. **包关联**
+   - 上传包后，需要在 Web UI 中手动关联到仓库
+   - 访问：http://gitea.xieyao.vip/xieyao/packages
+   - 选择仓库进行关联
+
+5. **代理设置**
+   - 如果使用了代理，需要取消代理后再访问 Gitea
+   ```bash
+   unset https_proxy all_proxy
+   ```
+
+---
+
+## 测试环境
+
+- **Gitea 服务器：** http://gitea.xieyao.vip/
+- **API 版本：** v1
+- **测试时间：** 2026-02-18
+- **操作人：** Geliebte
+
+---
+
+## 更新日志
+
+- **2026-02-18** - 初始版本，记录了三个核心 API 的使用方法