mirror of
https://codeberg.org/forgejo/forgejo.git
synced 2025-06-20 16:10:50 +00:00
Reformat docs (#13897)
Co-authored-by: 6543 <6543@obermui.de> Co-authored-by: Lauris BH <lauris@nix.lv>
This commit is contained in:
Patrick Schratz
GitHub
parent
97ab820acc
commit
af79677a44
86 changed files with 1115 additions and 957 deletions
|
|
@ -3,7 +3,7 @@ date: "2018-06-24:00:00+02:00"
|
|||
title: "API Usage"
|
||||
slug: "api-usage"
|
||||
weight: 40
|
||||
toc: true
|
||||
toc: false
|
||||
draft: false
|
||||
menu:
|
||||
sidebar:
|
||||
|
|
@ -15,12 +15,14 @@ menu:
|
|||
|
||||
# API Usage
|
||||
|
||||
**Table of Contents**
|
||||
|
||||
{{< toc >}}
|
||||
|
||||
## Enabling/configuring API access
|
||||
|
||||
By default, `ENABLE_SWAGGER` is true, and
|
||||
`MAX_RESPONSE_ITEMS` is set to 50. See [Config Cheat
|
||||
`MAX_RESPONSE_ITEMS` is set to 50. See [Config Cheat
|
||||
Sheet](https://docs.gitea.io/en-us/config-cheat-sheet/) for more
|
||||
information.
|
||||
|
||||
|
|
@ -33,7 +35,7 @@ Gitea supports these methods of API authentication:
|
|||
- `access_token=...` parameter in URL query string
|
||||
- `Authorization: token ...` header in HTTP headers
|
||||
|
||||
All of these methods accept the same API key token type. You can
|
||||
All of these methods accept the same API key token type. You can
|
||||
better understand this by looking at the code -- as of this writing,
|
||||
Gitea parses queries and headers to find the token in
|
||||
[modules/auth/auth.go](https://github.com/go-gitea/gitea/blob/6efdcaed86565c91a3dc77631372a9cc45a58e89/modules/auth/auth.go#L47).
|
||||
|
|
@ -54,13 +56,13 @@ Access tokens obtained from Gitea's [OAuth2 provider](https://docs.gitea.io/en-u
|
|||
For historical reasons, Gitea needs the word `token` included before
|
||||
the API key token in an authorization header, like this:
|
||||
|
||||
```
|
||||
```sh
|
||||
Authorization: token 65eaa9c8ef52460d22a93307fe0aee76289dc675
|
||||
```
|
||||
|
||||
In a `curl` command, for instance, this would look like:
|
||||
|
||||
```
|
||||
```sh
|
||||
curl -X POST "http://localhost:4000/api/v1/repos/test1/test1/issues" \
|
||||
-H "accept: application/json" \
|
||||
-H "Authorization: token 65eaa9c8ef52460d22a93307fe0aee76289dc675" \
|
||||
|
|
@ -73,10 +75,9 @@ the `token=` string in a GET request.
|
|||
## API Guide:
|
||||
|
||||
API Reference guide is auto-generated by swagger and available on:
|
||||
`https://gitea.your.host/api/swagger`
|
||||
or on
|
||||
[gitea demo instance](https://try.gitea.io/api/swagger)
|
||||
|
||||
`https://gitea.your.host/api/swagger`
|
||||
or on
|
||||
[gitea demo instance](https://try.gitea.io/api/swagger)
|
||||
|
||||
## Listing your issued tokens via the API
|
||||
|
||||
|
|
@ -87,14 +88,14 @@ using BasicAuth, as follows:
|
|||
|
||||
### Using basic authentication:
|
||||
|
||||
```
|
||||
```sh
|
||||
$ curl --request GET --url https://yourusername:yourpassword@gitea.your.host/api/v1/users/yourusername/tokens
|
||||
[{"name":"test","sha1":"..."},{"name":"dev","sha1":"..."}]
|
||||
```
|
||||
|
||||
As of v1.8.0 of Gitea, if using basic authentication with the API and your user has two factor authentication enabled, you'll need to send an additional header that contains the one time password (6 digit rotating token). An example of the header is `X-Gitea-OTP: 123456` where `123456` is where you'd place the code from your authenticator. Here is how the request would look like in curl:
|
||||
|
||||
```
|
||||
```sh
|
||||
$ curl -H "X-Gitea-OTP: 123456" --request GET --url https://yourusername:yourpassword@gitea.your.host/api/v1/users/yourusername/tokens
|
||||
```
|
||||
|
||||
|
|
@ -104,5 +105,5 @@ The API allows admin users to sudo API requests as another user. Simply add eith
|
|||
|
||||
## SDKs
|
||||
|
||||
* [Official go-sdk](https://gitea.com/gitea/go-sdk)
|
||||
* [more](https://gitea.com/gitea/awesome-gitea#user-content-sdk)
|
||||
- [Official go-sdk](https://gitea.com/gitea/go-sdk)
|
||||
- [more](https://gitea.com/gitea/awesome-gitea#user-content-sdk)
|
||||
|
|
|
|||
|
|
@ -3,7 +3,7 @@ date: "2018-06-24:00:00+02:00"
|
|||
title: "API 使用指南"
|
||||
slug: "api-usage"
|
||||
weight: 40
|
||||
toc: true
|
||||
toc: false
|
||||
draft: false
|
||||
menu:
|
||||
sidebar:
|
||||
|
|
|
|||
|
|
@ -15,6 +15,8 @@ menu:
|
|||
|
||||
# Hacking on Gitea
|
||||
|
||||
**Table of Contents**
|
||||
|
||||
{{< toc >}}
|
||||
|
||||
## Installing go
|
||||
|
|
@ -127,9 +129,9 @@ See `make help` for all available `make` targets. Also see [`.drone.yml`](https:
|
|||
|
||||
To run and continously rebuild when source files change:
|
||||
|
||||
````bash
|
||||
```bash
|
||||
make watch
|
||||
````
|
||||
```
|
||||
|
||||
On macOS, watching all backend source files may hit the default open files limit which can be increased via `ulimit -n 12288` for the current shell or in your shell startup file for all future shells.
|
||||
|
||||
|
|
@ -268,7 +270,7 @@ TAGS="bindata sqlite sqlite_unlock_notify" make build test-sqlite
|
|||
```
|
||||
|
||||
will run the integration tests in an sqlite environment. Integration tests
|
||||
require `git lfs` to be installed. Other database tests are available but
|
||||
require `git lfs` to be installed. Other database tests are available but
|
||||
may need adjustment to the local environment.
|
||||
|
||||
Look at
|
||||
|
|
|
|||
|
|
@ -3,7 +3,7 @@ date: "2019-04-15T17:29:00+08:00"
|
|||
title: "Integrations"
|
||||
slug: "integrations"
|
||||
weight: 40
|
||||
toc: true
|
||||
toc: false
|
||||
draft: false
|
||||
menu:
|
||||
sidebar:
|
||||
|
|
|
|||
|
|
@ -3,7 +3,7 @@ date: "2019-04-15T17:29:00+08:00"
|
|||
title: "Migrations Interfaces"
|
||||
slug: "migrations-interfaces"
|
||||
weight: 30
|
||||
toc: true
|
||||
toc: false
|
||||
draft: false
|
||||
menu:
|
||||
sidebar:
|
||||
|
|
|
|||
|
|
@ -3,7 +3,7 @@ date: "2019-04-19:44:00+01:00"
|
|||
title: "OAuth2 provider"
|
||||
slug: "oauth2-provider"
|
||||
weight: 41
|
||||
toc: true
|
||||
toc: false
|
||||
draft: false
|
||||
menu:
|
||||
sidebar:
|
||||
|
|
@ -13,25 +13,25 @@ menu:
|
|||
identifier: "oauth2-provider"
|
||||
---
|
||||
|
||||
|
||||
# OAuth2 provider
|
||||
|
||||
**Table of Contents**
|
||||
|
||||
{{< toc >}}
|
||||
|
||||
Gitea supports acting as an OAuth2 provider to allow third party applications to access its resources with the user's consent. This feature is available since release 1.8.0.
|
||||
|
||||
## Endpoints
|
||||
|
||||
|
||||
Endpoint | URL
|
||||
-----------------------|----------------------------
|
||||
Authorization Endpoint | `/login/oauth/authorize`
|
||||
Access Token Endpoint | `/login/oauth/access_token`
|
||||
|
||||
| Endpoint | URL |
|
||||
| ---------------------- | --------------------------- |
|
||||
| Authorization Endpoint | `/login/oauth/authorize` |
|
||||
| Access Token Endpoint | `/login/oauth/access_token` |
|
||||
|
||||
## Supported OAuth2 Grants
|
||||
|
||||
At the moment Gitea only supports the [**Authorization Code Grant**](https://tools.ietf.org/html/rfc6749#section-1.3.1) standard with additional support of the [Proof Key for Code Exchange (PKCE)](https://tools.ietf.org/html/rfc7636) extension.
|
||||
|
||||
|
||||
To use the Authorization Code Grant as a third party application it is required to register a new application via the "Settings" (`/user/settings/applications`) section of the settings.
|
||||
|
||||
## Scopes
|
||||
|
|
@ -44,49 +44,49 @@ Currently Gitea does not support scopes (see [#4300](https://github.com/go-gitea
|
|||
|
||||
1. Redirect to user to the authorization endpoint in order to get his/her consent for accessing the resources:
|
||||
|
||||
```curl
|
||||
https://[YOUR-GITEA-URL]/login/oauth/authorize?client_id=CLIENT_ID&redirect_uri=REDIRECT_URI& response_type=code&state=STATE
|
||||
```
|
||||
```curl
|
||||
https://[YOUR-GITEA-URL]/login/oauth/authorize?client_id=CLIENT_ID&redirect_uri=REDIRECT_URI& response_type=code&state=STATE
|
||||
```
|
||||
|
||||
The `CLIENT_ID` can be obtained by registering an application in the settings. The `STATE` is a random string that will be send back to your application after the user authorizes. The `state` parameter is optional but should be used to prevent CSRF attacks.
|
||||
The `CLIENT_ID` can be obtained by registering an application in the settings. The `STATE` is a random string that will be send back to your application after the user authorizes. The `state` parameter is optional but should be used to prevent CSRF attacks.
|
||||
|
||||
|
||||
|
||||
|
||||
The user will now be asked to authorize your application. If they authorize it, the user will be redirected to the `REDIRECT_URL`, for example:
|
||||
|
||||
The user will now be asked to authorize your application. If they authorize it, the user will be redirected to the `REDIRECT_URL`, for example:
|
||||
```curl
|
||||
https://[REDIRECT_URI]?code=RETURNED_CODE&state=STATE
|
||||
```
|
||||
|
||||
```curl
|
||||
https://[REDIRECT_URI]?code=RETURNED_CODE&state=STATE
|
||||
```
|
||||
2. Using the provided `code` from the redirect, you can request a new application and refresh token. The access token endpoints accepts POST requests with `application/json` and `application/x-www-form-urlencoded` body, for example:
|
||||
|
||||
2. Using the provided `code` from the redirect, you can request a new application and refresh token. The access token endpoints accepts POST requests with `application/json` and `application/x-www-form-urlencoded` body, for example:
|
||||
```curl
|
||||
POST https://[YOUR-GITEA-URL]/login/oauth/access_token
|
||||
```
|
||||
|
||||
```curl
|
||||
POST https://[YOUR-GITEA-URL]/login/oauth/access_token
|
||||
```
|
||||
```json
|
||||
{
|
||||
"client_id": "YOUR_CLIENT_ID",
|
||||
"client_secret": "YOUR_CLIENT_SECRET",
|
||||
"code": "RETURNED_CODE",
|
||||
"grant_type": "authorization_code",
|
||||
"redirect_uri": "REDIRECT_URI"
|
||||
}
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"client_id": "YOUR_CLIENT_ID",
|
||||
"client_secret": "YOUR_CLIENT_SECRET",
|
||||
"code": "RETURNED_CODE",
|
||||
"grant_type": "authorization_code",
|
||||
"redirect_uri": "REDIRECT_URI"
|
||||
}
|
||||
```
|
||||
Response:
|
||||
|
||||
Response:
|
||||
```json
|
||||
{
|
||||
"access_token":"eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJnbnQiOjIsInR0IjowLCJleHAiOjE1NTUxNzk5MTIsImlhdCI6MTU1NTE3NjMxMn0.0-iFsAwBtxuckA0sNZ6QpBQmywVPz129u75vOM7wPJecw5wqGyBkmstfJHAjEOqrAf_V5Z-1QYeCh_Cz4RiKug",
|
||||
"token_type":"bearer",
|
||||
"expires_in":3600,
|
||||
"refresh_token":"eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJnbnQiOjIsInR0IjoxLCJjbnQiOjEsImV4cCI6MTU1NzgwNDMxMiwiaWF0IjoxNTU1MTc2MzEyfQ.S_HZQBy4q9r5SEzNGNIoFClT43HPNDbUdHH-GYNYYdkRfft6XptJBkUQscZsGxOW975Yk6RbgtGvq1nkEcklOw"
|
||||
}
|
||||
```
|
||||
```json
|
||||
{
|
||||
"access_token": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJnbnQiOjIsInR0IjowLCJleHAiOjE1NTUxNzk5MTIsImlhdCI6MTU1NTE3NjMxMn0.0-iFsAwBtxuckA0sNZ6QpBQmywVPz129u75vOM7wPJecw5wqGyBkmstfJHAjEOqrAf_V5Z-1QYeCh_Cz4RiKug",
|
||||
"token_type": "bearer",
|
||||
"expires_in": 3600,
|
||||
"refresh_token": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJnbnQiOjIsInR0IjoxLCJjbnQiOjEsImV4cCI6MTU1NzgwNDMxMiwiaWF0IjoxNTU1MTc2MzEyfQ.S_HZQBy4q9r5SEzNGNIoFClT43HPNDbUdHH-GYNYYdkRfft6XptJBkUQscZsGxOW975Yk6RbgtGvq1nkEcklOw"
|
||||
}
|
||||
```
|
||||
|
||||
The `CLIENT_SECRET` is the unique secret code generated for this application. Please note that the secret will only be visible after you created/registered the application with Gitea and cannot be recovered. If you lose the secret you must regenerate the secret via the application's settings.
|
||||
The `CLIENT_SECRET` is the unique secret code generated for this application. Please note that the secret will only be visible after you created/registered the application with Gitea and cannot be recovered. If you lose the secret you must regenerate the secret via the application's settings.
|
||||
|
||||
The `REDIRECT_URI` in the `access_token` request must match the `REDIRECT_URI` in the `authorize` request.
|
||||
The `REDIRECT_URI` in the `access_token` request must match the `REDIRECT_URI` in the `authorize` request.
|
||||
|
||||
3. Use the `access_token` to make [API requests](https://docs.gitea.io/en-us/api-usage#oauth2) to access the user's resources.
|
||||
3. Use the `access_token` to make [API requests](https://docs.gitea.io/en-us/api-usage#oauth2) to access the user's resources.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue