Frodo swaggins (#126)

* more swagger fun

* document a whole bunch more stuff

* more swagger yayyyyyyy

* progress + go fmt

internal/api/client/account/accountcreate.go

@@ -30,13 +30,13 @@ import (
 	"github.com/superseriousbusiness/gotosocial/internal/util"
 )
 
-// AccountCreatePOSTHandler handles create account requests, validates them,
-// and puts them in the database if they're valid.
-//
-// swagger:operation POST /api/v1/accounts accountCreate
+// AccountCreatePOSTHandler swagger:operation POST /api/v1/accounts accountCreate
 //
 // Create a new account using an application token.
 //
+// The parameters can also be given in the body of the request, as JSON, if the content-type is set to 'application/json'.
+// The parameters can also be given in the body of the request, as XML, if the content-type is set to 'application/xml'.
+//
 // ---
 // tags:
 // - accounts
@@ -45,17 +45,10 @@ import (
 // - application/json
 // - application/xml
 // - application/x-www-form-urlencoded
-// - multipart/form-data
 //
 // produces:
 // - application/json
 //
-// parameters:
-// - name: Account Create Request
-//   in: body
-//   schema:
-//     "$ref": "#/definitions/accountCreateRequest"
-//
 // security:
 // - OAuth2 Application:
 //   - write:accounts

internal/api/client/account/accountget.go

@@ -25,9 +25,7 @@ import (
 	"github.com/superseriousbusiness/gotosocial/internal/oauth"
 )
 
-// AccountGETHandler returns info about the given account.
-//
-// swagger:operation GET /api/v1/accounts/{id} accountGet
+// AccountGETHandler swagger:operation GET /api/v1/accounts/{id} accountGet
 //
 // Get information about an account with the given ID.
 //

internal/api/client/account/accountupdate.go

@@ -26,10 +26,7 @@ import (
 	"github.com/superseriousbusiness/gotosocial/internal/oauth"
 )
 
-// AccountUpdateCredentialsPATCHHandler allows a user to modify their account/profile settings.
-// It should be served as a PATCH at /api/v1/accounts/update_credentials
-//
-// swagger:operation PATCH /api/v1/accounts/update_credentials accountUpdate
+// AccountUpdateCredentialsPATCHHandler swagger:operation PATCH /api/v1/accounts/update_credentials accountUpdate
 //
 // Update your account.
 //
@@ -56,10 +53,12 @@ import (
 //   in: formData
 //   description: The display name to use for the account.
 //   type: string
+//   allowEmptyValue: true
 // - name: note
 //   in: formData
 //   description: Bio/description of this account.
 //   type: string
+//   allowEmptyValue: true
 // - name: avatar
 //   in: formData
 //   description: Avatar of the user.
@@ -72,15 +71,15 @@ import (
 //   in: formData
 //   description: Require manual approval of follow requests.
 //   type: boolean
-// - name: source.privacy
+// - name: source[privacy]
 //   in: formData
 //   description: Default post privacy for authored statuses.
 //   type: string
-// - name: source.sensitive
+// - name: source[sensitive]
 //   in: formData
 //   description: Mark authored statuses as sensitive by default.
 //   type: boolean
-// - name: source.language
+// - name: source[language]
 //   in: formData
 //   description: Default language to use for authored statuses (ISO 6391).
 //   type: string

internal/api/client/account/accountverify.go

@@ -25,11 +25,7 @@ import (
 	"github.com/superseriousbusiness/gotosocial/internal/oauth"
 )
 
-// AccountVerifyGETHandler serves a user's account details to them IF they reached this
-// handler while in possession of a valid token, according to the oauth middleware.
-// It should be served as a GET at /api/v1/accounts/verify_credentials.
-//
-// swagger:operation GET /api/v1/accounts/verify_credentials accountVerify
+// AccountVerifyGETHandler swagger:operation GET /api/v1/accounts/verify_credentials accountVerify
 //
 // Verify a token by returning account details pertaining to it.
 //

internal/api/client/account/block.go

@@ -25,9 +25,7 @@ import (
 	"github.com/superseriousbusiness/gotosocial/internal/oauth"
 )
 
-// AccountBlockPOSTHandler handles the creation of a block from the authed account targeting the given account ID.
-//
-// swagger:operation POST /api/v1/accounts/{id}/block accountBlock
+// AccountBlockPOSTHandler swagger:operation POST /api/v1/accounts/{id}/block accountBlock
 //
 // Block account with id.
 //

internal/api/client/account/follow.go

@@ -26,25 +26,43 @@ import (
 	"github.com/superseriousbusiness/gotosocial/internal/oauth"
 )
 
-// AccountFollowPOSTHandler is the endpoint for creating a new follow request to the target account
-//
-// swagger:operation POST /api/v1/accounts/{id}/follow accountFollow
+// AccountFollowPOSTHandler swagger:operation POST /api/v1/accounts/{id}/follow accountFollow
 //
 // Follow account with id.
 //
+// The parameters can also be given in the body of the request, as JSON, if the content-type is set to 'application/json'.
+// The parameters can also be given in the body of the request, as XML, if the content-type is set to 'application/xml'.
+//
 // ---
 // tags:
 // - accounts
 //
-// produces:
+// consumes:
 // - application/json
+// - application/xml
+// - application/x-www-form-urlencoded
 //
 // parameters:
 // - name: id
-//   type: string
-//   description: The id of the account to follow.
-//   in: path
 //   required: true
+//   in: path
+//   description: ID of the account to follow.
+//   type: string
+// - default: true
+//   description: Show reblogs from this account.
+//   in: formData
+//   name: reblogs
+//   type: boolean
+//   x-go-name: Reblogs
+// - default: false
+//   description: Notify when this account posts.
+//   in: formData
+//   name: notify
+//   type: boolean
+//   x-go-name: Notify
+//
+// produces:
+// - application/json
 //
 // security:
 // - OAuth2 Bearer:
@@ -79,7 +97,7 @@ func (m *Module) AccountFollowPOSTHandler(c *gin.Context) {
 		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
 		return
 	}
-	form.TargetAccountID = targetAcctID
+	form.ID = targetAcctID
 
 	relationship, errWithCode := m.processor.AccountFollowCreate(authed, form)
 	if errWithCode != nil {

internal/api/client/account/followers.go

@@ -25,9 +25,7 @@ import (
 	"github.com/superseriousbusiness/gotosocial/internal/oauth"
 )
 
-// AccountFollowersGETHandler serves the followers of the requested account, if they're visible to the requester.
-//
-// swagger:operation GET /api/v1/accounts/{id}/followers accountFollowers
+// AccountFollowersGETHandler swagger:operation GET /api/v1/accounts/{id}/followers accountFollowers
 //
 // See followers of account with given id.
 //

internal/api/client/account/following.go

@@ -25,9 +25,7 @@ import (
 	"github.com/superseriousbusiness/gotosocial/internal/oauth"
 )
 
-// AccountFollowingGETHandler serves the following of the requested account, if they're visible to the requester.
-//
-// swagger:operation GET /api/v1/accounts/{id}/following accountFollowing
+// AccountFollowingGETHandler swagger:operation GET /api/v1/accounts/{id}/following accountFollowing
 //
 // See accounts followed by given account id.
 //

internal/api/client/account/relationships.go

@@ -8,9 +8,7 @@ import (
 	"github.com/superseriousbusiness/gotosocial/internal/oauth"
 )
 
-// AccountRelationshipsGETHandler serves the relationship of the requesting account with one or more requested account IDs.
-//
-// swagger:operation GET /api/v1/accounts/relationships accountRelationships
+// AccountRelationshipsGETHandler swagger:operation GET /api/v1/accounts/relationships accountRelationships
 //
 // See your account's relationships with the given account IDs.
 //

internal/api/client/account/statuses.go

@@ -26,9 +26,7 @@ import (
 	"github.com/superseriousbusiness/gotosocial/internal/oauth"
 )
 
-// AccountStatusesGETHandler serves the statuses of the requested account, if they're visible to the requester.
-//
-// swagger:operation GET /api/v1/accounts/{id}/statuses accountStatuses
+// AccountStatusesGETHandler swagger:operation GET /api/v1/accounts/{id}/statuses accountStatuses
 //
 // See statuses posted by the requested account.
 //
@@ -86,7 +84,7 @@ import (
 // responses:
 //   '200':
 //     name: statuses
-//     description: Array of statuses..
+//     description: Array of statuses.
 //     schema:
 //       type: array
 //       items:

internal/api/client/account/unblock.go

@@ -25,9 +25,7 @@ import (
 	"github.com/superseriousbusiness/gotosocial/internal/oauth"
 )
 
-// AccountUnblockPOSTHandler handles the removal of a block from the authed account targeting the given account ID.
-//
-// swagger:operation POST /api/v1/accounts/{id}/unblock accountUnblock
+// AccountUnblockPOSTHandler swagger:operation POST /api/v1/accounts/{id}/unblock accountUnblock
 //
 // Unblock account with ID.
 //

internal/api/client/account/unfollow.go

@@ -25,9 +25,7 @@ import (
 	"github.com/superseriousbusiness/gotosocial/internal/oauth"
 )
 
-// AccountUnfollowPOSTHandler is the endpoint for removing a follow and/or follow request to the target account
-//
-// swagger:operation POST /api/v1/accounts/{id}/unfollow accountUnfollow
+// AccountUnfollowPOSTHandler swagger:operation POST /api/v1/accounts/{id}/unfollow accountUnfollow
 //
 // Unfollow account with id.
 //