diff options
Diffstat (limited to 'docs/api/swagger.md')
| -rw-r--r-- | docs/api/swagger.md | 18 |
1 files changed, 15 insertions, 3 deletions
diff --git a/docs/api/swagger.md b/docs/api/swagger.md index c31d6185a..ae9670b9f 100644 --- a/docs/api/swagger.md +++ b/docs/api/swagger.md @@ -1,9 +1,21 @@ -# API Documentation +# Routes and Methods GoToSocial uses [go-swagger](https://github.com/go-swagger/go-swagger) to generate a V2 [OpenAPI specification](https://swagger.io/specification/v2/) document from code annotations. -The resulting API documentation is rendered below, for quick reference. +The resulting API documentation is rendered below. Please note that the doc is intended for reference only. You will not be able to use the built-in Authorize functionality in the below widget to actually connect to an instance or make API calls. Instead, you should use something like curl, Postman, or similar. -If you'd like to do more with the spec, you can also view the [swagger.yaml](./swagger.yaml) directly, and then paste it into something like the [Swagger Editor](https://editor.swagger.io/) in order to autogenerate GoToSocial API clients in different languages, convert the doc to JSON or OpenAPI v3 specification, etc. See [here](https://swagger.io/tools/open-source/getting-started/) for more. +Most of the GoToSocial API endpoints require a user-level OAuth token. For a guide on how to authenticate with the API using an OAuth token, see the [authentication doc](./authentication.md). + +!!! tip + If you'd like to do more with the spec, you can also view the [swagger.yaml](./swagger.yaml) directly, and then paste it into something like the [Swagger Editor](https://editor.swagger.io/). That way you can try autogenerating GoToSocial API clients in different languages (not supported, but fun), or convert the doc to JSON or OpenAPI v3 specification, etc. See [here](https://swagger.io/tools/open-source/getting-started/) for more. + +!!! info "Gotcha: uploading files" + When using an API endpoint that involves submitting a form to upload files (eg., the media attachments endpoints, or the emoji upload endpoint, etc), please note that `filename` is a required on the form field, due to the dependency that GoToSocial uses to parse forms, and some quirks in Go. + + See the following issues for more context: + + - [#1958](https://github.com/superseriousbusiness/gotosocial/issues/1958) + - [#1944](https://github.com/superseriousbusiness/gotosocial/issues/1944) + - [#2641](https://github.com/superseriousbusiness/gotosocial/issues/2641) <swagger-ui src="swagger.yaml"/> |