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

* [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>

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