[bugfix/docs] Poll api fixups + swagger docs (#2345)

internal/api/client/polls/polls_vote.go

@@ -27,7 +27,7 @@ import (
 	"github.com/superseriousbusiness/gotosocial/internal/oauth"
 )
 
-// PollVotePOSTHandler swagger:operation POST /api/v1/polls/{id}/vote poll
+// PollVotePOSTHandler swagger:operation POST /api/v1/polls/{id}/vote pollVote
 //
 // Vote with choices in the given poll.
 //
@@ -45,6 +45,14 @@ import (
 //		description: Target poll ID.
 //		in: path
 //		required: true
+//	-
+//		name: choices
+//		type: array
+//		items:
+//			type: integer
+//		description: Poll choice indices on which to vote.
+//		in: formData
+//		required: true
 //
 //	security:
 //	- OAuth2 Bearer:

internal/api/model/poll.go

@@ -41,10 +41,15 @@ type Poll struct {
 	VotersCount int `json:"voters_count"`
 
 	// When called with a user token, has the authorized user voted?
-	Voted bool `json:"voted,omitempty"`
+	//
+	// Omitted when no user token provided.
+	Voted *bool `json:"voted,omitempty"`
 
-	// When called with a user token, which options has the authorized user chosen? Contains an array of index values for options.
-	OwnVotes []int `json:"own_votes,omitempty"`
+	// When called with a user token, which options has the authorized
+	// user chosen? Contains an array of index values for options.
+	//
+	// Omitted when no user token provided.
+	OwnVotes *[]int `json:"own_votes,omitempty"`
 
 	// Possible answers for the poll.
 	Options []PollOption `json:"options"`
@@ -66,7 +71,7 @@ type PollOption struct {
 
 // PollRequest models a request to create a poll.
 //
-// swagger:parameters createStatus
+// swagger:model pollRequest
 type PollRequest struct {
 	// Array of possible answers.
 	// If provided, media_ids cannot be used, and poll[expires_in] must be provided.
@@ -86,7 +91,7 @@ type PollRequest struct {
 
 // PollVoteRequest models a request to vote in a poll.
 //
-// swagger:parameters pollVote
+// swagger:ignore
 type PollVoteRequest struct {
 	// Choices contains poll vote choice indices. Note that form
 	// uses a different key than the JSON, i.e. the '[]' suffix.

internal/api/model/status.go

@@ -155,7 +155,7 @@ type StatusCreateRequest struct {
 	// in: formData
 	MediaIDs []string `form:"media_ids[]" json:"media_ids" xml:"media_ids"`
 	// Poll to include with this status.
-	// swagger:ignore
+	// in: formData
 	Poll *PollRequest `form:"poll" json:"poll" xml:"poll"`
 	// ID of the status being replied to, if status is a reply.
 	// in: formData

internal/typeutils/internaltofrontend.go

@@ -1313,8 +1313,10 @@ func (c *Converter) PollToAPIPoll(ctx context.Context, requester *gtsmodel.Accou
 		options     []apimodel.PollOption
 		totalVotes  int
 		totalVoters int
-		ownChoices  []int
+		voted       *bool
+		ownChoices  *[]int
 		isAuthor    bool
+		emojis      []apimodel.Emoji
 	)
 
 	// Preallocate a slice of frontend model poll choices.
@@ -1337,19 +1339,26 @@ func (c *Converter) PollToAPIPoll(ctx context.Context, requester *gtsmodel.Accou
 
 		if vote != nil {
 			// Set choices by requester.
-			ownChoices = vote.Choices
+			ownChoices = &vote.Choices
 
 			// Update default totals in the
 			// case that counts are hidden.
 			totalVotes = len(vote.Choices)
 			totalVoters = 1
-			for _, choice := range ownChoices {
+			for _, choice := range *ownChoices {
 				options[choice].VotesCount++
 			}
+		} else {
+			// Requester is defined but hasn't made
+			// a choice. Init slice to serialize as `[]`.
+			ownChoices = util.Ptr(make([]int, 0))
 		}
 
 		// Check if requester is author of source status.
 		isAuthor = (requester.ID == poll.Status.AccountID)
+
+		// Requester is defined so voted should be defined too.
+		voted = util.Ptr((isAuthor || len(*ownChoices) > 0))
 	}
 
 	if isAuthor || !*poll.HideCounts {
@@ -1368,6 +1377,11 @@ func (c *Converter) PollToAPIPoll(ctx context.Context, requester *gtsmodel.Accou
 		}
 	}
 
+	// TODO: emojis used in poll options.
+	// For now init to empty slice to serialize as `[]`.
+	// In future inherit from parent status.
+	emojis = make([]apimodel.Emoji, 0)
+
 	return &apimodel.Poll{
 		ID:          poll.ID,
 		ExpiresAt:   util.FormatISO8601(poll.ExpiresAt),
@@ -1375,9 +1389,10 @@ func (c *Converter) PollToAPIPoll(ctx context.Context, requester *gtsmodel.Accou
 		Multiple:    (*poll.Multiple),
 		VotesCount:  totalVotes,
 		VotersCount: totalVoters,
-		Voted:       (isAuthor || len(ownChoices) > 0),
+		Voted:       voted,
 		OwnVotes:    ownChoices,
 		Options:     options,
+		Emojis:      emojis,
 	}, nil
 }