Frodo swaggins (#126)

* more swagger fun

* document a whole bunch more stuff

* more swagger yayyyyyyy

* progress + go fmt

1 files changed, 68 insertions, 22 deletions

diff --git a/internal/api/model/status.go b/internal/api/model/status.go
index 919fb3e37..c5b5a4640 100644
--- a/internal/api/model/status.go
+++ b/internal/api/model/status.go
@@ -18,7 +18,7 @@
 
 package model
 
-// Status represents a status or post.
+// Status models a status or post.
 //
 // swagger:model status
 type Status struct {
@@ -71,8 +71,9 @@ type Status struct {
 	// The content of this status. Should be HTML, but might also be plaintext in some cases.
 	// example: <p>Hey this is a status!</p>
 	Content string `json:"content"`
-	// The status that this status is a reblog/boost of.
-	Reblog *Status `json:"reblog,omitempty"`
+	// The status that this status reblogs/boosts.
+	// nullable: true
+	Reblog *StatusReblogged `json:"reblog,omitempty"`
 	// The application used to post this status, if visible.
 	Application *Application `json:"application"`
 	// The account that authored this status.
@@ -95,35 +96,71 @@ type Status struct {
 	Text string `json:"text"`
 }
 
-// StatusCreateRequest represents a mastodon-api status POST request, as defined here: https://docs.joinmastodon.org/methods/statuses/
-// It should be used at the path https://mastodon.example/api/v1/statuses
+// StatusReblogged represents a reblogged status.
+//
+// swagger:model statusReblogged
+type StatusReblogged struct {
+	*Status
+}
+
+// StatusCreateRequest models status creation parameters.
+//
+// swagger:parameters statusCreate
 type StatusCreateRequest struct {
-	// Text content of the status. If media_ids is provided, this becomes optional. Attaching a poll is optional while status is provided.
+	// Text content of the status.
+	// If media_ids is provided, this becomes optional.
+	// Attaching a poll is optional while status is provided.
+	// in: formData
 	Status string `form:"status" json:"status" xml:"status"`
-	// Array of Attachment ids to be attached as media. If provided, status becomes optional, and poll cannot be used.
+	// Array of Attachment ids to be attached as media.
+	// If provided, status becomes optional, and poll cannot be used.
+	// in: formData
 	MediaIDs []string `form:"media_ids" json:"media_ids" xml:"media_ids"`
 	// Poll to include with this status.
+	// swagger:ignore
 	Poll *PollRequest `form:"poll" json:"poll" xml:"poll"`
-	// ID of the status being replied to, if status is a reply
+	// ID of the status being replied to, if status is a reply.
+	// in: formData
 	InReplyToID string `form:"in_reply_to_id" json:"in_reply_to_id" xml:"in_reply_to_id"`
-	// Mark status and attached media as sensitive?
+	// Status and attached media should be marked as sensitive.
+	// in: formData
 	Sensitive bool `form:"sensitive" json:"sensitive" xml:"sensitive"`
-	// Text to be shown as a warning or subject before the actual content. Statuses are generally collapsed behind this field.
+	// Text to be shown as a warning or subject before the actual content.
+	// Statuses are generally collapsed behind this field.
+	// in: formData
 	SpoilerText string `form:"spoiler_text" json:"spoiler_text" xml:"spoiler_text"`
-	// Visibility of the posted status. Enumerable oneOf public, unlisted, private, direct.
+	// Visibility of the posted status.
+	// enum:
+	// - public
+	// - unlisted
+	// - private
+	// - direct
+	// in: formData
 	Visibility Visibility `form:"visibility" json:"visibility" xml:"visibility"`
-	// ISO 8601 Datetime at which to schedule a status. Providing this paramter will cause ScheduledStatus to be returned instead of Status. Must be at least 5 minutes in the future.
+	// ISO 8601 Datetime at which to schedule a status.
+	// Providing this paramter will cause ScheduledStatus to be returned instead of Status.
+	// Must be at least 5 minutes in the future.
+	// in: formData
 	ScheduledAt string `form:"scheduled_at" json:"scheduled_at" xml:"scheduled_at"`
 	// ISO 639 language code for this status.
+	// in: formData
 	Language string `form:"language" json:"language" xml:"language"`
-	// Format in which to parse the submitted status.
-	// Can be either plain or markdown. Empty will default to plain.
+	// Format to use when parsing this status.
+	// enum:
+	// - markdown
+	// - plain
+	// in: formData
 	Format StatusFormat `form:"format" json:"format" xml:"format"`
 }
 
-// Visibility denotes the visibility of a status to other users.
+// Visibility models the visibility of a status.
 //
 // swagger:model statusVisibility
+// enum:
+// - public
+// - unlisted
+// - private
+// - direct
 type Visibility string
 
 const (
@@ -141,6 +178,8 @@ const (
 
 // AdvancedStatusCreateForm wraps the mastodon status create form along with the GTS advanced
 // visibility settings.
+//
+// swagger:model advancedStatusCreateForm
 type AdvancedStatusCreateForm struct {
 	StatusCreateRequest
 	AdvancedVisibilityFlagsForm
@@ -148,20 +187,27 @@ type AdvancedStatusCreateForm struct {
 
 // AdvancedVisibilityFlagsForm allows a few more advanced flags to be set on new statuses, in addition
 // to the standard mastodon-compatible ones.
+//
+// swagger:model advancedVisibilityFlagsForm
 type AdvancedVisibilityFlagsForm struct {
-	// The gotosocial visibility model
-	VisibilityAdvanced *string `form:"visibility_advanced" json:"visibility_advanced" xml:"visibility_advanced"`
-	// This status will be federated beyond the local timeline(s)
+	// This status will be federated beyond the local timeline(s).
 	Federated *bool `form:"federated" json:"federated" xml:"federated"`
-	// This status can be boosted/reblogged
+	// This status can be boosted/reblogged.
 	Boostable *bool `form:"boostable" json:"boostable" xml:"boostable"`
-	// This status can be replied to
+	// This status can be replied to.
 	Replyable *bool `form:"replyable" json:"replyable" xml:"replyable"`
-	// This status can be liked/faved
+	// This status can be liked/faved.
 	Likeable *bool `form:"likeable" json:"likeable" xml:"likeable"`
 }
 
-// StatusFormat determines what kind of format a submitted status should be parsed in
+// StatusFormat is the format in which to parse the submitted status.
+// Can be either plain or markdown. Empty will default to plain.
+//
+// swagger:model statusFormat
+// enum:
+// - plain
+// - markdown
+// example: plain
 type StatusFormat string
 
 // StatusFormatPlain expects a plaintext status which will then be formatted into html.