diff --git a/docs/content/doc/advanced/api-usage.zh-cn.md b/docs/content/doc/advanced/api-usage.zh-cn.md new file mode 100644 index 000000000..de02a24b0 --- /dev/null +++ b/docs/content/doc/advanced/api-usage.zh-cn.md @@ -0,0 +1,71 @@ +--- +date: "2018-06-24:00:00+02:00" +title: "API 使用指南" +slug: "api-usage" +weight: 40 +toc: true +draft: false +menu: + sidebar: + parent: "advanced" + name: "API 使用指南" + weight: 40 + identifier: "api-usage" +--- + +# Gitea API 使用指南 + +## 开启/配置 API 访问 + +通常情况下， `ENABLE_SWAGGER_ENDPOINT` 默认开启并且参数 `MAX_RESPONSE_ITEMS` 默认为 50。您可以从 [Config Cheat +Sheet](https://docs.gitea.io/en-us/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](https://github.com/go-gitea/gitea/blob/6efdcaed86565c91a3dc77631372a9cc45a58e89/modules/auth/auth.go#L47) 中找到。 + +您可以通过您的 gitea web 界面来创建 apiKey token： +`Settings | Applications | Generate New Token`. + +### 关于 `Authorization:` header + +由于一些历史原因，Gitea 需要在 header 的 apiKey token 里引入前缀 `token`，类似于如下形式： + +``` +Authorization: token 65eaa9c8ef52460d22a93307fe0aee76289dc675 +``` + +以 `curl` 命令为例，它会以如下形式携带在请求中： + +``` +curl -X POST "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](https://github.com/go-gitea/gitea/issues/3842#issuecomment-397743346) 有所提及，使用方法如下所示： + +### 使用 Basic authentication 认证： + +``` +$ curl --request GET --url https://yourusername:yourpassword@gitea.your.host/api/v1/users/yourusername/tokens +[{"name":"test","sha1":"..."},{"name":"dev","sha1":"..."}] +``` + +## 使用 Sudo 方式请求 API + +此 API 允许管理员借用其他用户身份进行 API 请求。只需在请求中指定查询参数 `sudo=` 或是指定 header 中的 `Sudo:` 为需要使用的用户 username 即可。 diff --git a/docs/content/doc/advanced/customizing-gitea.zh-cn.md b/docs/content/doc/advanced/customizing-gitea.zh-cn.md new file mode 100644 index 000000000..21068496a --- /dev/null +++ b/docs/content/doc/advanced/customizing-gitea.zh-cn.md @@ -0,0 +1,88 @@ +--- +date: "2017-04-15T14:56:00+02:00" +title: "自定义 Gitea 配置" +slug: "customizing-gitea" +weight: 9 +toc: false +draft: false +menu: + sidebar: + parent: "advanced" + name: "自定义 Gitea 配置" + weight: 9 + identifier: "customizing-gitea" +--- + +# 自定义 Gitea 配置 + +Gitea 引用 `custom` 目录中的自定义配置文件来覆盖配置、模板等默认配置。 + +如果从二进制部署 Gitea ，则所有默认路径都将相对于该 gitea 二进制文件；如果从发行版安装，则可能会将这些路径修改为Linux文件系统标准。Gitea +将会自动创建包括 `custom/` 在内的必要应用目录，应用本身的配置存放在 +`custom/conf/app.ini` 当中。在发行版中可能会以 `/etc/gitea/` 的形式为 `custom` 设置一个符号链接，查看配置详情请移步： + +- [快速备忘单](https://docs.gitea.io/en-us/config-cheat-sheet/) +- [完整配置清单](https://github.com/go-gitea/gitea/blob/master/custom/conf/app.ini.sample) + +如果您在 binary 同目录下无法找到 `custom` 文件夹，请检查您的 `GITEA_CUSTOM` +环境变量配置， 因为它可能被配置到了其他地方（可能被一些启动脚本设置指定了目录）。 + +- [环境变量清单](https://docs.gitea.io/en-us/specific-variables/) + +**注：** 必须完全重启 Gitea 以使配置生效。 + +## 使用自定义 /robots.txt + +将 [想要展示的内容](http://www.robotstxt.org/) 存放在 `custom` 目录中的 +`robots.txt` 文件来让 Gitea 使用自定义的`/robots.txt` （默认：空 404）。 + +## 使用自定义的公共文件 + +将自定义的公共文件（比如页面和图片）作为 webroot 放在 `custom/public/` 中来让 Gitea 提供这些自定义内容（符号链接将被追踪）。 + +举例说明：`image.png` 存放在 `custom/public/`中，那么它可以通过链接 http://gitea.domain.tld/image.png 访问。 + +## 修改默认头像 + +替换以下目录中的 png 图片： `custom/public/img/avatar\_default.png` + +## 自定义 Gitea 页面 + +您可以改变 Gitea `custom/templates` 的每个单页面。您可以在 Gitea 源码的 `templates` 目录中找到用于覆盖的模板文件，应用将根据 +`custom/templates` 目录下的路径结构进行匹配和覆盖。 + +包含在 `{{` 和 `}}` 中的任何语句都是 Gitea 的模板语法，如果您不完全理解这些组件，不建议您对它们进行修改。 + +### 添加链接和页签 + +如果您只是想添加额外的链接到顶部导航栏或额外的选项卡到存储库视图，您可以将它们放在您 `custom/templates/custom/` 目录下的 `extra_links.tmpl` 和 `extra_tabs.tmpl` 文件中。 + +举例说明：假设您在德国，必须添加着名的法律要求的“Impressum”用以罗列谁负责网站的内容页面，您只需将该页面放在您的 +"custom/public/"目录下（比如 `custom/public/impressum.html`）并且将它与 `custom/templates/custom/extra_links.tmpl` 链接起来即可。 + +这个链接应当使用一个名为“item”的 class 来匹配当前样式，您可以使用 `{{AppSubUrl}}` 来获取 base URL: +`Impressum` + +同理，您可以将页签添加到 `extra_tabs.tmpl` 中，使用同样的方式来添加页签。它的具体样式需要与 +`templates/repo/header.tmpl` 中已有的其他选项卡的样式匹配 +([source in GitHub](https://github.com/go-gitea/gitea/blob/master/templates/repo/header.tmpl)) + +### 页面的其他新增内容 + +除了 `extra_links.tmpl` 和 `extra_tabs.tmpl`，您可以在您的 `custom/templates/custom/` 目录中存放一些其他有用的模板，例如： + +- `header.tmpl`，在 `` 标记结束之前的模板，例如添加自定义CSS文件 +- `body_outer_pre.tmpl`，在 `` 标记开始处的模板 +- `body_inner_pre.tmpl`，在顶部导航栏之前，但在主 container 内部的模板，例如添加一个 `
` +- `body_inner_post.tmpl`，在主 container 结束处的模板 +- `body_outer_post.tmpl`，在底部 `