Swagger (#124)

* start experimenting with swagger documentation

* further adventures in swagger

* do a few more api paths

* account paths documented

* go fmt

* fix up some models

* bit o lintin'

internal/api/client/account/accountcreate.go

@@ -32,13 +32,53 @@ import (
 
 // AccountCreatePOSTHandler handles create account requests, validates them,
 // and puts them in the database if they're valid.
-// It should be served as a POST at /api/v1/accounts
+//
+// swagger:operation POST /api/v1/accounts accountCreate
+//
+// Create a new account using an application token.
+//
+// ---
+// tags:
+// - accounts
+//
+// consumes:
+// - 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
+//
+// responses:
+//   '200':
+//     description: "An OAuth2 access token for the newly-created account."
+//     schema:
+//       "$ref": "#/definitions/oauthToken"
+//   '401':
+//      description: unauthorized
+//   '400':
+//      description: bad request
+//   '404':
+//      description: not found
+//   '500':
+//      description: internal error
 func (m *Module) AccountCreatePOSTHandler(c *gin.Context) {
 	l := m.log.WithField("func", "accountCreatePOSTHandler")
 	authed, err := oauth.Authed(c, true, true, false, false)
 	if err != nil {
 		l.Debugf("couldn't auth: %s", err)
-		c.JSON(http.StatusForbidden, gin.H{"error": err.Error()})
+		c.JSON(http.StatusUnauthorized, gin.H{"error": err.Error()})
 		return
 	}
 

internal/api/client/account/accountget.go

@@ -25,12 +25,42 @@ import (
 	"github.com/superseriousbusiness/gotosocial/internal/oauth"
 )
 
-// AccountGETHandler serves the account information held by the server in response to a GET
-// request. It should be served as a GET at /api/v1/accounts/:id.
+// AccountGETHandler returns info about the given account.
 //
-// See: https://docs.joinmastodon.org/methods/accounts/
+// swagger:operation GET /api/v1/accounts/{id} accountGet
+//
+// Get information about an account with the given ID.
+//
+// ---
+// tags:
+// - accounts
+//
+// produces:
+// - application/json
+//
+// parameters:
+// - name: id
+//   type: string
+//   description: The id of the requested account.
+//   in: path
+//   required: true
+//
+// security:
+// - OAuth2 Bearer:
+//   - read:accounts
+//
+// responses:
+//   '200':
+//     schema:
+//       "$ref": "#/definitions/account"
+//   '401':
+//      description: unauthorized
+//   '400':
+//      description: bad request
+//   '404':
+//      description: not found
 func (m *Module) AccountGETHandler(c *gin.Context) {
-	authed, err := oauth.Authed(c, false, false, false, false)
+	authed, err := oauth.Authed(c, true, true, true, true)
 	if err != nil {
 		c.JSON(http.StatusUnauthorized, gin.H{"error": "unauthorized"})
 		return

internal/api/client/account/accountupdate.go

@@ -29,14 +29,78 @@ import (
 // AccountUpdateCredentialsPATCHHandler allows a user to modify their account/profile settings.
 // It should be served as a PATCH at /api/v1/accounts/update_credentials
 //
-// TODO: this can be optimized massively by building up a picture of what we want the new account
-// details to be, and then inserting it all in the database at once. As it is, we do queries one-by-one
-// which is not gonna make the database very happy when lots of requests are going through.
-// This way it would also be safer because the update won't happen until *all* the fields are validated.
-// Otherwise we risk doing a partial update and that's gonna cause probllleeemmmsss.
+// swagger:operation PATCH /api/v1/accounts/update_credentials accountUpdate
+//
+// Update your account.
+//
+// ---
+// tags:
+// - accounts
+//
+// consumes:
+// - multipart/form-data
+//
+// produces:
+// - application/json
+//
+// parameters:
+// - name: discoverable
+//   in: formData
+//   description: Account should be made discoverable and shown in the profile directory (if enabled).
+//   type: boolean
+// - name: bot
+//   in: formData
+//   description: Account is flagged as a bot.
+//   type: boolean
+// - name: display_name
+//   in: formData
+//   description: The display name to use for the account.
+//   type: string
+// - name: note
+//   in: formData
+//   description: Bio/description of this account.
+//   type: string
+// - name: avatar
+//   in: formData
+//   description: Avatar of the user.
+//   type: file
+// - name: header
+//   in: formData
+//   description: Header of the user.
+//   type: file
+// - name: locked
+//   in: formData
+//   description: Require manual approval of follow requests.
+//   type: boolean
+// - name: source.privacy
+//   in: formData
+//   description: Default post privacy for authored statuses.
+//   type: string
+// - name: source.sensitive
+//   in: formData
+//   description: Mark authored statuses as sensitive by default.
+//   type: boolean
+// - name: source.language
+//   in: formData
+//   description: Default language to use for authored statuses (ISO 6391).
+//   type: string
+//
+// security:
+// - OAuth2 Bearer:
+//   - write:accounts
+//
+// responses:
+//   '200':
+//     description: "The newly updated account."
+//     schema:
+//       "$ref": "#/definitions/account"
+//   '401':
+//      description: unauthorized
+//   '400':
+//      description: bad request
 func (m *Module) AccountUpdateCredentialsPATCHHandler(c *gin.Context) {
 	l := m.log.WithField("func", "accountUpdateCredentialsPATCHHandler")
-	authed, err := oauth.Authed(c, true, false, false, true)
+	authed, err := oauth.Authed(c, true, true, true, true)
 	if err != nil {
 		l.Debugf("couldn't auth: %s", err)
 		c.JSON(http.StatusForbidden, gin.H{"error": err.Error()})

internal/api/client/account/accountverify.go

@@ -27,7 +27,33 @@ import (
 
 // 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
+// It should be served as a GET at /api/v1/accounts/verify_credentials.
+//
+// swagger:operation GET /api/v1/accounts/verify_credentials accountVerify
+//
+// Verify a token by returning account details pertaining to it.
+//
+// ---
+// tags:
+// - accounts
+//
+// produces:
+// - application/json
+//
+// security:
+// - OAuth2 Bearer:
+//   - read:accounts
+//
+// responses:
+//   '200':
+//     schema:
+//       "$ref": "#/definitions/account"
+//   '401':
+//      description: unauthorized
+//   '400':
+//      description: bad request
+//   '404':
+//      description: not found
 func (m *Module) AccountVerifyGETHandler(c *gin.Context) {
 	l := m.log.WithField("func", "accountVerifyGETHandler")
 	authed, err := oauth.Authed(c, true, false, false, true)

internal/api/client/account/block.go

@@ -26,6 +26,41 @@ import (
 )
 
 // 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
+//
+// Block account with id.
+//
+// ---
+// tags:
+// - accounts
+//
+// produces:
+// - application/json
+//
+// parameters:
+// - name: id
+//   type: string
+//   description: The id of the account to block.
+//   in: path
+//   required: true
+//
+// security:
+// - OAuth2 Bearer:
+//   - write:blocks
+//
+// responses:
+//   '200':
+//     name: account relationship
+//     description: Your relationship to this account.
+//     schema:
+//       "$ref": "#/definitions/accountRelationship"
+//   '401':
+//      description: unauthorized
+//   '400':
+//      description: bad request
+//   '404':
+//      description: not found
 func (m *Module) AccountBlockPOSTHandler(c *gin.Context) {
 	authed, err := oauth.Authed(c, true, true, true, true)
 	if err != nil {

internal/api/client/account/follow.go

@@ -27,6 +27,41 @@ import (
 )
 
 // AccountFollowPOSTHandler is the endpoint for creating a new follow request to the target account
+//
+// swagger:operation POST /api/v1/accounts/{id}/follow accountFollow
+//
+// Follow account with id.
+//
+// ---
+// tags:
+// - accounts
+//
+// produces:
+// - application/json
+//
+// parameters:
+// - name: id
+//   type: string
+//   description: The id of the account to follow.
+//   in: path
+//   required: true
+//
+// security:
+// - OAuth2 Bearer:
+//   - write:follows
+//
+// responses:
+//   '200':
+//     name: account relationship
+//     description: Your relationship to this account.
+//     schema:
+//       "$ref": "#/definitions/accountRelationship"
+//   '401':
+//      description: unauthorized
+//   '400':
+//      description: bad request
+//   '404':
+//      description: not found
 func (m *Module) AccountFollowPOSTHandler(c *gin.Context) {
 	authed, err := oauth.Authed(c, true, true, true, true)
 	if err != nil {

internal/api/client/account/followers.go

@@ -26,6 +26,43 @@ import (
 )
 
 // AccountFollowersGETHandler serves the followers of the requested account, if they're visible to the requester.
+//
+// swagger:operation GET /api/v1/accounts/{id}/followers accountFollowers
+//
+// See followers of account with given id.
+//
+// ---
+// tags:
+// - accounts
+//
+// produces:
+// - application/json
+//
+// parameters:
+// - name: id
+//   type: string
+//   description: Account ID.
+//   in: path
+//   required: true
+//
+// security:
+// - OAuth2 Bearer:
+//   - read:accounts
+//
+// responses:
+//   '200':
+//     name: accounts
+//     description: Array of accounts that follow this account.
+//     schema:
+//       type: array
+//       items:
+//         "$ref": "#/definitions/account"
+//   '401':
+//      description: unauthorized
+//   '400':
+//      description: bad request
+//   '404':
+//      description: not found
 func (m *Module) AccountFollowersGETHandler(c *gin.Context) {
 	authed, err := oauth.Authed(c, true, true, true, true)
 	if err != nil {

internal/api/client/account/following.go

@@ -26,6 +26,43 @@ import (
 )
 
 // AccountFollowingGETHandler serves the following of the requested account, if they're visible to the requester.
+//
+// swagger:operation GET /api/v1/accounts/{id}/following accountFollowing
+//
+// See accounts followed by given account id.
+//
+// ---
+// tags:
+// - accounts
+//
+// produces:
+// - application/json
+//
+// parameters:
+// - name: id
+//   type: string
+//   description: Account ID.
+//   in: path
+//   required: true
+//
+// security:
+// - OAuth2 Bearer:
+//   - read:accounts
+//
+// responses:
+//   '200':
+//     name: accounts
+//     description: Array of accounts that are followed by this account.
+//     schema:
+//       type: array
+//       items:
+//         "$ref": "#/definitions/account"
+//   '401':
+//      description: unauthorized
+//   '400':
+//      description: bad request
+//   '404':
+//      description: not found
 func (m *Module) AccountFollowingGETHandler(c *gin.Context) {
 	authed, err := oauth.Authed(c, true, true, true, true)
 	if err != nil {

internal/api/client/account/relationships.go

@@ -9,6 +9,45 @@ import (
 )
 
 // AccountRelationshipsGETHandler serves the relationship of the requesting account with one or more requested account IDs.
+//
+// swagger:operation GET /api/v1/accounts/relationships accountRelationships
+//
+// See your account's relationships with the given account IDs.
+//
+// ---
+// tags:
+// - accounts
+//
+// produces:
+// - application/json
+//
+// parameters:
+// - name: id
+//   type: array
+//   items:
+//     type: string
+//   description: Account IDs.
+//   in: query
+//   required: true
+//
+// security:
+// - OAuth2 Bearer:
+//   - read:accounts
+//
+// responses:
+//   '200':
+//     name: account relationships
+//     description: Array of account relationships.
+//     schema:
+//       type: array
+//       items:
+//         "$ref": "#/definitions/accountRelationship"
+//   '401':
+//      description: unauthorized
+//   '400':
+//      description: bad request
+//   '404':
+//      description: not found
 func (m *Module) AccountRelationshipsGETHandler(c *gin.Context) {
 	l := m.log.WithField("func", "AccountRelationshipsGETHandler")
 

internal/api/client/account/statuses.go

@@ -28,13 +28,75 @@ import (
 
 // AccountStatusesGETHandler serves the statuses of the requested account, if they're visible to the requester.
 //
-// Several different filters might be passed into this function in the query:
+// swagger:operation GET /api/v1/accounts/{id}/statuses accountStatuses
 //
-// 	limit -- show only limit number of statuses
-// 	exclude_replies -- exclude statuses that are a reply to another status
-// 	max_id -- the maximum ID of the status to show
-// 	pinned -- show only pinned statuses
-// 	media_only -- show only statuses that have media attachments
+// See statuses posted by the requested account.
+//
+// The statuses will be returned in descending chronological order (newest first), with sequential IDs (bigger = newer).
+//
+// ---
+// tags:
+// - accounts
+//
+// produces:
+// - application/json
+//
+// parameters:
+// - name: id
+//   type: string
+//   description: Account ID.
+//   in: path
+//   required: true
+// - name: limit
+//   type: integer
+//   description: Number of statuses to return.
+//   default: 30
+//   in: query
+//   required: false
+// - name: exclude_replies
+//   type: boolean
+//   description: Exclude statuses that are a reply to another status.
+//   default: false
+//   in: query
+//   required: false
+// - name: max_id
+//   type: string
+//   description: |-
+//     Return only statuses *OLDER* than the given max status ID.
+//     The status with the specified ID will not be included in the response.
+//   in: query
+//   required: false
+// - name: pinned_only
+//   type: boolean
+//   description: Show only pinned statuses. In other words,e xclude statuses that are not pinned to the given account ID.
+//   default: false
+//   in: query
+//   required: false
+// - name: media_only
+//   type: boolean
+//   description: Show only statuses with media attachments.
+//   default: false
+//   in: query
+//   required: false
+//
+// security:
+// - OAuth2 Bearer:
+//   - read:accounts
+//
+// responses:
+//   '200':
+//     name: statuses
+//     description: Array of statuses..
+//     schema:
+//       type: array
+//       items:
+//         "$ref": "#/definitions/status"
+//   '401':
+//      description: unauthorized
+//   '400':
+//      description: bad request
+//   '404':
+//      description: not found
 func (m *Module) AccountStatusesGETHandler(c *gin.Context) {
 	l := m.log.WithField("func", "AccountStatusesGETHandler")
 

internal/api/client/account/unblock.go

@@ -26,6 +26,41 @@ import (
 )
 
 // 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
+//
+// Unblock account with ID.
+//
+// ---
+// tags:
+// - accounts
+//
+// produces:
+// - application/json
+//
+// parameters:
+// - name: id
+//   type: string
+//   description: The id of the account to unblock.
+//   in: path
+//   required: true
+//
+// security:
+// - OAuth2 Bearer:
+//   - write:blocks
+//
+// responses:
+//   '200':
+//     name: account relationship
+//     description: Your relationship to this account.
+//     schema:
+//       "$ref": "#/definitions/accountRelationship"
+//   '401':
+//      description: unauthorized
+//   '400':
+//      description: bad request
+//   '404':
+//      description: not found
 func (m *Module) AccountUnblockPOSTHandler(c *gin.Context) {
 	authed, err := oauth.Authed(c, true, true, true, true)
 	if err != nil {

internal/api/client/account/unfollow.go

@@ -26,6 +26,41 @@ import (
 )
 
 // 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
+//
+// Unfollow account with id.
+//
+// ---
+// tags:
+// - accounts
+//
+// produces:
+// - application/json
+//
+// parameters:
+// - name: id
+//   type: string
+//   description: The id of the account to unfollow.
+//   in: path
+//   required: true
+//
+// security:
+// - OAuth2 Bearer:
+//   - write:follows
+//
+// responses:
+//   '200':
+//     name: account relationship
+//     description: Your relationship to this account.
+//     schema:
+//       "$ref": "#/definitions/accountRelationship"
+//   '401':
+//      description: unauthorized
+//   '400':
+//      description: bad request
+//   '404':
+//      description: not found
 func (m *Module) AccountUnfollowPOSTHandler(c *gin.Context) {
 	l := m.log.WithField("func", "AccountUnfollowPOSTHandler")
 	authed, err := oauth.Authed(c, true, true, true, true)