code.gitea.io/gitea@v1.22.3/docs/content/development/api-usage.zh-cn.md (about)

     1  ---
     2  date: "2018-06-24:00:00+02:00"
     3  title: "API 使用指南"
     4  slug: "api-usage"
     5  sidebar_position: 40
     6  toc: false
     7  draft: false
     8  aliases:
     9    - /zh-cn/api-usage
    10  menu:
    11    sidebar:
    12      parent: "development"
    13      name: "API 使用指南"
    14      sidebar_position: 40
    15      identifier: "api-usage"
    16  ---
    17  
    18  # Gitea API 使用指南
    19  
    20  ## 开启/配置 API 访问
    21  
    22  通常情况下， `ENABLE_SWAGGER` 默认开启并且参数 `MAX_RESPONSE_ITEMS` 默认为 50。您可以从 [Config Cheat Sheet](administration/config-cheat-sheet.md) 中获取更多配置相关信息。
    23  
    24  ## 通过 API 认证
    25  
    26  Gitea 支持以下几种 API 认证方式：
    27  
    28  - HTTP basic authentication 方式
    29  - 通过指定 `token=...` URL 查询参数方式
    30  - 通过指定 `access_token=...` URL 查询参数方式
    31  - 通过指定 `Authorization: token ...` HTTP header 方式
    32  
    33  以上提及的认证方法接受相同的 apiKey token 类型，您可以在编码时通过查阅代码更好地理解这一点。
    34  Gitea 调用解析查询参数以及头部信息来获取 token 的代码可以在 [modules/auth/auth.go](https://github.com/go-gitea/gitea/blob/6efdcaed86565c91a3dc77631372a9cc45a58e89/modules/auth/auth.go#L47) 中找到。
    35  
    36  您可以通过您的 gitea web 界面来创建 apiKey token：
    37  `Settings | Applications | Generate New Token`.
    38  
    39  ### 关于 `Authorization:` header
    40  
    41  由于一些历史原因，Gitea 需要在 header 的 apiKey token 里引入前缀 `token`，类似于如下形式：
    42  
    43  ```
    44  Authorization: token 65eaa9c8ef52460d22a93307fe0aee76289dc675
    45  ```
    46  
    47  以 `curl` 命令为例，它会以如下形式携带在请求中：
    48  
    49  ```
    50  curl "http://localhost:4000/api/v1/repos/test1/test1/issues" \
    51      -H "accept: application/json" \
    52      -H "Authorization: token 65eaa9c8ef52460d22a93307fe0aee76289dc675" \
    53      -H "Content-Type: application/json" -d "{ \"body\": \"testing\", \"title\": \"test 20\"}" -i
    54  ```
    55  
    56  正如上例所示，您也可以在 GET 请求中使用同一个 token 并以 `token=` 的查询参数形式携带 token 来进行认证。
    57  
    58  ## 通过 API 列出您发布的令牌
    59  
    60  `/users/:name/tokens` 是一个特殊的接口，需要您使用 basic authentication 进行认证，具体原因在 issue 中
    61  [#3842](https://github.com/go-gitea/gitea/issues/3842#issuecomment-397743346) 有所提及，使用方法如下所示：
    62  
    63  ### 使用 Basic authentication 认证
    64  
    65  ```
    66  $ curl --url https://yourusername:yourpassword@gitea.your.host/api/v1/users/yourusername/tokens
    67  [{"name":"test","sha1":"..."},{"name":"dev","sha1":"..."}]
    68  ```
    69  
    70  ## 使用 Sudo 方式请求 API
    71  
    72  此 API 允许管理员借用其他用户身份进行 API 请求。只需在请求中指定查询参数 `sudo=` 或是指定 header 中的 `Sudo:` 为需要使用的用户 username 即可。