mirrors/gotosocial
1
0
Fork 0
mirror of https://github.com/superseriousbusiness/gotosocial.git synced 2025-10-29 04:22:24 -05:00
Code Issues Projects Releases Packages Wiki Activity Actions

[chore/docs] Various little docs updates (#2691)

Browse source 
* [chore/docs] Various little docs updates

* Update docs/api/swagger.md

Co-authored-by: Daenney <daenney@users.noreply.github.com>

---------

Co-authored-by: kim <89579420+NyaaaWhatsUpDoc@users.noreply.github.com>
Co-authored-by: Daenney <daenney@users.noreply.github.com>
This commit is contained in:
tobi 2024-02-27 15:39:22 +01:00 • committed by GitHub
commit feb6abbab2
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
4 changed files with 18 additions and 10 deletions
Download patch file Download diff file Expand all files Collapse all files

18
docs/api/swagger.md
View file

@ -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"/>