tidy up follow request api

internal/api/client/followrequest/authorize.go

@@ -26,14 +26,53 @@ import (
 	"github.com/superseriousbusiness/gotosocial/internal/oauth"
 )
 
-// FollowRequestAcceptPOSTHandler deals with follow request accepting. It should be served at
-// /api/v1/follow_requests/:id/authorize
-func (m *Module) FollowRequestAcceptPOSTHandler(c *gin.Context) {
-	l := logrus.WithField("func", "statusCreatePOSTHandler")
+// FollowRequestAuthorizePOSTHandler swagger:operation POST /api/v1/follow_requests/{account_id}/authorize authorizeFollowRequest
+//
+// Accept/authorize follow request from the given account ID.
+//
+// Accept a follow request and put the requesting account in your 'followers' list.
+//
+// ---
+// tags:
+// - follow_requests
+//
+// produces:
+// - application/json
+//
+// parameters:
+// - name: account_id
+//   type: string
+//   description: ID of the account requesting to follow you.
+//   in: path
+//   required: true
+//
+// security:
+// - OAuth2 Bearer:
+//   - write:follows
+//
+// responses:
+//   '200':
+//     name: account relationship
+//     description: Your relationship to this account.
+//     schema:
+//       "$ref": "#/definitions/accountRelationship"
+//   '400':
+//      description: bad request
+//   '401':
+//      description: unauthorized
+//   '403':
+//      description: forbidden
+//   '404':
+//      description: not found
+//   '500':
+//      description: internal server error
+func (m *Module) FollowRequestAuthorizePOSTHandler(c *gin.Context) {
+	l := logrus.WithField("func", "FollowRequestAuthorizePOSTHandler")
+
 	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()})
+		c.JSON(http.StatusUnauthorized, gin.H{"error": err.Error()})
 		return
 	}
 
@@ -49,11 +88,12 @@ func (m *Module) FollowRequestAcceptPOSTHandler(c *gin.Context) {
 		return
 	}
 
-	r, errWithCode := m.processor.FollowRequestAccept(c.Request.Context(), authed, originAccountID)
+	relationship, errWithCode := m.processor.FollowRequestAccept(c.Request.Context(), authed, originAccountID)
 	if errWithCode != nil {
 		l.Debug(errWithCode.Error())
 		c.JSON(errWithCode.Code(), gin.H{"error": errWithCode.Safe()})
 		return
 	}
-	c.JSON(http.StatusOK, r)
+
+	c.JSON(http.StatusOK, relationship)
 }

internal/api/client/followrequest/followrequest.go

@@ -28,21 +28,20 @@ import (
 )
 
 const (
-	// IDKey is for status UUIDs
+	// IDKey is for account IDs
 	IDKey = "id"
 	// BasePath is the base path for serving the follow request API
 	BasePath = "/api/v1/follow_requests"
 	// BasePathWithID is just the base path with the ID key in it.
-	// Use this anywhere you need to know the ID of the follow request being queried.
+	// Use this anywhere you need to know the ID of the account that owns the follow request being queried.
 	BasePathWithID = BasePath + "/:" + IDKey
-
-	// AcceptPath is used for accepting follow requests
-	AcceptPath = BasePathWithID + "/authorize"
-	// DenyPath is used for denying follow requests
-	DenyPath = BasePathWithID + "/reject"
+	// AuthorizePath is used for authorizing follow requests
+	AuthorizePath = BasePathWithID + "/authorize"
+	// RejectPath is used for rejecting follow requests
+	RejectPath = BasePathWithID + "/reject"
 )
 
-// Module implements the ClientAPIModule interface for every related to interacting with follow requests
+// Module implements the ClientAPIModule interface
 type Module struct {
 	config    *config.Config
 	processor processing.Processor
@@ -59,7 +58,7 @@ func New(config *config.Config, processor processing.Processor) api.ClientModule
 // Route attaches all routes from this module to the given router
 func (m *Module) Route(r router.Router) error {
 	r.AttachHandler(http.MethodGet, BasePath, m.FollowRequestGETHandler)
-	r.AttachHandler(http.MethodPost, AcceptPath, m.FollowRequestAcceptPOSTHandler)
-	r.AttachHandler(http.MethodPost, DenyPath, m.FollowRequestDenyPOSTHandler)
+	r.AttachHandler(http.MethodPost, AuthorizePath, m.FollowRequestAuthorizePOSTHandler)
+	r.AttachHandler(http.MethodPost, RejectPath, m.FollowRequestRejectPOSTHandler)
 	return nil
 }

internal/api/client/followrequest/get.go

@@ -26,13 +26,60 @@ import (
 	"github.com/superseriousbusiness/gotosocial/internal/oauth"
 )
 
-// FollowRequestGETHandler allows clients to get a list of their incoming follow requests.
+// FollowRequestGETHandler swagger:operation GET /api/v1/follow_requests getFollowRequests
+//
+// Get an array of accounts that have requested to follow you.
+//
+// The next and previous queries can be parsed from the returned Link header.
+// Example:
+//
+// ```
+// <https://example.org/api/v1/follow_requests?limit=80&max_id=01FC0SKA48HNSVR6YKZCQGS2V8>; rel="next", <https://example.org/api/v1/follow_requests?limit=80&min_id=01FC0SKW5JK2Q4EVAV2B462YY0>; rel="prev"
+// ````
+//
+// ---
+// tags:
+// - follow_requests
+//
+// produces:
+// - application/json
+//
+// parameters:
+// - name: limit
+//   type: integer
+//   description: Number of accounts to return.
+//   default: 40
+//   in: query
+//
+// security:
+// - OAuth2 Bearer:
+//   - read:follows
+//
+// responses:
+//   '200':
+//     headers:
+//       Link:
+//         type: string
+//         description: Links to the next and previous queries.
+//     schema:
+//       type: array
+//       items:
+//         "$ref": "#/definitions/account"
+//   '400':
+//      description: bad request
+//   '401':
+//      description: unauthorized
+//   '403':
+//      description: forbidden
+//   '404':
+//      description: not found
 func (m *Module) FollowRequestGETHandler(c *gin.Context) {
-	l := logrus.WithField("func", "statusCreatePOSTHandler")
+	l := logrus.WithField("func", "FollowRequestGETHandler")
+
 	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()})
+		c.JSON(http.StatusUnauthorized, gin.H{"error": err.Error()})
 		return
 	}