跳至主要内容
版本: 1.22.3

API 使用

启用/配置 API 访问​

默认情况下，ENABLE_SWAGGER 为 true，MAX_RESPONSE_ITEMS 设置为 50。有关更多信息，请参阅 配置速查表。

身份验证​

Gitea 支持以下 API 身份验证方法

  • HTTP 基本身份验证
  • URL 查询字符串中的 token=... 参数
  • URL 查询字符串中的 access_token=... 参数
  • HTTP 头部中的 Authorization: token ... 头部

所有这些方法都接受相同的 API 密钥令牌类型。您可以通过查看代码更好地理解这一点 - 在撰写本文时，Gitea 解析查询和标头以在 modules/auth/auth.go 中查找令牌。

生成和列出 API 令牌​

可以使用 POST 请求到 /users/:name/tokens 生成新的令牌。

请注意，/users/:name/tokens 是一个特殊的端点，需要您使用 BasicAuth 和密码进行身份验证，如下所示

$ curl -H "Content-Type: application/json" -d '{"name":"test"}' -u username:password https://gitea.your.host/api/v1/users/<username>/tokens
{"id":1,"name":"test","sha1":"9fcb1158165773dd010fca5f0cf7174316c3e37d","token_last_eight":"16c3e37d"}

sha1（令牌）仅返回一次，并且不会以明文形式存储。在使用 GET 请求列出令牌时不会显示它；例如：

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

要使用启用了双因素身份验证的基本身份验证的 API，您需要发送一个包含一次性密码（6 位旋转令牌）的附加标头。标头的示例为 X-Gitea-OTP: 123456，其中 123456 是您放置身份验证器代码的位置。以下是 curl 请求的示例：

$ curl -H "X-Gitea-OTP: 123456" --url https://yourusername:[email protected]/api/v1/users/yourusername/tokens

您也可以通过 Gitea 安装的 Web 界面创建 API 密钥令牌：设置 | 应用程序 | 生成新令牌。

OAuth2 提供者​

从 Gitea 的 OAuth2 提供者 获取的访问令牌被这些方法接受

  • HTTP 头部中的 Authorization bearer ... 头部
  • URL 查询字符串中的 token=... 参数
  • URL 查询字符串中的 access_token=... 参数

关于 Authorization: 标头的更多信息​

出于历史原因，Gitea 需要在授权标头中的 API 密钥令牌之前包含单词 token，如下所示

Authorization: token 65eaa9c8ef52460d22a93307fe0aee76289dc675

例如，在 curl 命令中，这将如下所示

curl "https://127.0.0.1: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= 字符串中使用的令牌相同。

分页​

API 支持分页。page 和 limit 参数用于指定页码和每页项目数。此外，如果有多个页面，则会返回 Link 标头，其中包含下一页、上一页和最后一页的链接。x-total-count 也被返回以指示项目的总数。

curl -v "https://127.0.0.1/api/v1/repos/search?limit=1"
...
< link: <https://127.0.0.1/api/v1/repos/search?limit=1&page=2>; rel="next",<https://127.0.0.1/api/v1/repos/search?limit=1&page=5252>; rel="last"
...
< x-total-count: 5252

API 指南​

API 参考指南由 swagger 自动生成，可在以下位置获得：https://gitea.your.host/api/swagger 或 Gitea 实例 上

OpenAPI 文档位于：https://gitea.your.host/swagger.v1.json

Sudo​

API 允许管理员用户以其他用户身份执行 sudo API 请求。只需添加 sudo= 参数或 Sudo: 请求标头，其中包含要执行 sudo 的用户的用户名。

SDK​