From feb6abbab2c0ec9e5eb4af6cba430ab9206be695 Mon Sep 17 00:00:00 2001 From: tobi <31960611+tsmethurst@users.noreply.github.com> Date: Tue, 27 Feb 2024 15:39:22 +0100 Subject: [PATCH] [chore/docs] Various little docs updates (#2691) * [chore/docs] Various little docs updates * Update docs/api/swagger.md Co-authored-by: Daenney --------- Co-authored-by: kim <89579420+NyaaaWhatsUpDoc@users.noreply.github.com> Co-authored-by: Daenney --- docs/api/swagger.md | 18 +++++++++++++++--- docs/faq.md | 4 ---- mkdocs.yml | 4 ++-- web/source/settings/user/migration.tsx | 2 +- 4 files changed, 18 insertions(+), 10 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) diff --git a/docs/faq.md b/docs/faq.md index 23403d363..8645efa5e 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -46,10 +46,6 @@ Take a look at the [list of open bugs](https://github.com/superseriousbusiness/g - account migration - shared block lists across servers -## Warnings “authentication NOT PASSED for public key” in the log - -These warnings are caused by Mastodon forgetting to take query parameters into account when signing HTTP requests. Fixes on both Mastodon and GoToSocial sides are in the works, and other instance software is expected to follow. - ## Will you support tables in Markdown? Not at the moment, as most clients handle them terribly. diff --git a/mkdocs.yml b/mkdocs.yml index b183add00..173b7aa03 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -123,8 +123,8 @@ nav: - "federation/index.md" - "federation/glossary.md" - "federation/federating_with_gotosocial.md" - - "API Documentation": - - "api/swagger.md" + - "Client API Docs": - "api/authentication.md" + - "api/swagger.md" - "api/ratelimiting.md" - "api/throttling.md" diff --git a/web/source/settings/user/migration.tsx b/web/source/settings/user/migration.tsx index ddfc71cdd..d0c5e3393 100644 --- a/web/source/settings/user/migration.tsx +++ b/web/source/settings/user/migration.tsx @@ -48,7 +48,7 @@ function UserMigrationForm({ data: profile }) {

Account Migration Settings

- Moving your account to another instance, or moving an account from another instance to your account, isn't implemented yet! See here for progress. + Moving your account to another instance, or moving an account from another instance to your account, isn't implemented yet! You will only be able to use the "alias" section of the below panel. See here for progress.

The following settings allow you to alias your account to another account