Gitea API 使用指南

最近重新研究了下Git服务器Gitea的使用，完成了从Gitlab仓库迁移到Gitea的运维工作，对于这两个Git服务器的API使用有了初步的了解。在使用的过程中发现网络上的资料相对较少，而且内容介绍还不细致全面，下面将Gitea API使用中遇到的问题和感受记录如下。

使用Gitea API可以完成对仓库信息的查看和统计，通过程序可以完成一些手工重复性的工作。Gitea服务器运行后提供有关API的Swagger文档。默认的地址为：http://localhost:3000/api/swagger

Gitea API需要授权用户才能访问，我主要使用了网页登录的基本权限控制方式（HTTP basic authentication）和发布令牌（Token）的方式。个人认为HTTP basic authentication 比较易用一些，使用Token需要用户在配置中设置私人令牌，而且只在创建时显示令牌内容容易遗忘，重新创建令牌会增加额外的工作，而且程序也必须进行相应的修改。基本的权限控制方式只要提供用户名和密码，一般创建之后不会发生变化，但是有安全性问题。

开启/配置 API 访问

通常情况下， ENABLE_SWAGGER 默认开启。并且参数 MAX_RESPONSE_ITEMS 默认为 50。您可以从 Config Cheat Sheet 中获取更多配置相关信息。

通过 API 认证

Gitea 支持以下几种 API 认证方式：

• HTTP basic authentication 方式
• 通过指定 token=... URL 查询参数方式
• 通过指定 access_token=... URL 查询参数方式
• 通过指定 Authorization: token ... HTTP header 方式

以上提及的认证方法接受相同的 apiKey token 类型，您可以在编码时通过查阅代码更好地理解这一点。 Gitea 调用解析查询参数以及头部信息来获取 token 的代码可以在 modules/auth/auth.go 中找到。

您可以通过您的 gitea web 界面来创建 apiKey token： Settings | Applications | Generate New Token.

关于 Authorization: header

由于一些历史原因，Gitea 需要在 header 的 apiKey token 里引入前缀 token，类似于如下形式：

Authorization: token 65eaa9c8ef52460d22a93307fe0aee76289dc675
以 curl 命令为例，它会以如下形式携带在请求中：

curl "http://localhost:4000/api/v1/repos/test1/test1/issues" \
-H "accept: application/json" \
-H "Authorization: token 65eaa9c8ef52460d22a93307fe0aee76289dc675" \
-H "Content-Type: application/json" -d "{ \"body\": \"testing\", \"title\": \"test 20\"}" -i
正如上例所示，您也可以在 GET 请求中使用同一个 token 并以 token= 的查询参数形式携带 token 来进行认证。

通过 API 列出您发布的令牌

/users/:name/tokens 是一个特殊的接口，需要您使用 basic authentication 进行认证，具体原因在 issue 中 #3842 有所提及，使用方法如下所示：

使用 Basic authentication 认证

$ curl --url https://yourusername:[email protected]/api/v1/users/yourusername/tokens[{"name":"test","sha1":"..."},{"name":"dev","sha1":"..."}]

参考资料：

https://docs.gitea.io/zh-cn/api-usage/  Gitea API 使用指南