Frodo swaggins (#126)

* more swagger fun

* document a whole bunch more stuff

* more swagger yayyyyyyy

* progress + go fmt

12 files changed, 399 insertions, 178 deletions

diff --git a/internal/api/model/account.go b/internal/api/model/account.go
index 1e02e38ec..38f03d787 100644
--- a/internal/api/model/account.go
+++ b/internal/api/model/account.go
@@ -23,7 +23,9 @@ import (
 	"net"
 )
 
-// Account represents a fediverse account of some kind, either a remote one or one on this instance.
+// Account models a fediverse account.
+//
+// The modelled account can be either a remote account, or one on this instance.
 //
 // swagger:model account
 type Account struct {
@@ -42,7 +44,7 @@ type Account struct {
 	DisplayName string `json:"display_name"`
 	// Account manually approves follow requests.
 	Locked bool `json:"locked"`
-	// Account has opted into discovery features such as the profile directory.
+	// Account has opted into discovery features.
 	Discoverable bool `json:"discoverable,omitempty"`
 	// Account identifies as a bot.
 	Bot bool `json:"bot"`
@@ -90,9 +92,9 @@ type Account struct {
 	Source *Source `json:"source,omitempty"`
 }
 
-// AccountCreateRequest represents the form submitted during a POST request to /api/v1/accounts.
+// AccountCreateRequest models account creation parameters.
 //
-// swagger:model accountCreateRequest
+// swagger:parameters accountCreate
 type AccountCreateRequest struct {
 	// Text that will be reviewed by moderators if registrations require manual approval.
 	Reason string `form:"reason" json:"reason" xml:"reason"`
@@ -127,7 +129,8 @@ type AccountCreateRequest struct {
 	IP net.IP `form:"-"`
 }
 
-// UpdateCredentialsRequest represents the form submitted during a PATCH request to /api/v1/accounts/update_credentials.
+// UpdateCredentialsRequest models an update to an account, by the account owner.
+//
 // swagger:ignore
 type UpdateCredentialsRequest struct {
 	// Account should be made discoverable and shown in the profile directory (if enabled).
@@ -151,7 +154,8 @@ type UpdateCredentialsRequest struct {
 }
 
 // UpdateSource is to be used specifically in an UpdateCredentialsRequest.
-// swagger:ignore
+//
+// swagger:model updateSource
 type UpdateSource struct {
 	// Default post privacy for authored statuses.
 	Privacy *string `form:"privacy" json:"privacy" xml:"privacy"`
@@ -172,15 +176,14 @@ type UpdateField struct {
 	Value *string `form:"value" json:"value" xml:"value"`
 }
 
-// AccountFollowRequest is for parsing requests at /api/v1/accounts/:id/follow
+// AccountFollowRequest models a request to follow an account.
 //
-// swagger:model accountFollowRequest
+// swagger:ignore
 type AccountFollowRequest struct {
-	// ID of the account to follow request
-	// This should be a URL parameter not a form field
-	TargetAccountID string `form:"-"`
-	// Show reblogs for this account?
+	// The id of the account to follow.
+	ID string `form:"-" json:"-" xml:"-"`
+	// Show reblogs from this account.
 	Reblogs *bool `form:"reblogs" json:"reblogs" xml:"reblogs"`
-	// Notify when this account posts?
+	// Notify when this account posts.
 	Notify *bool `form:"notify" json:"notify" xml:"notify"`
 }
diff --git a/internal/api/model/admin.go b/internal/api/model/admin.go
index 036218f77..301c4efa9 100644
--- a/internal/api/model/admin.go
+++ b/internal/api/model/admin.go
@@ -18,7 +18,7 @@
 
 package model
 
-// AdminAccountInfo represents the *admin* view of an account's details. See here: https://docs.joinmastodon.org/entities/admin-account/
+// AdminAccountInfo models the admin view of an account's details.
 type AdminAccountInfo struct {
 	// The ID of the account in the database.
 	ID string `json:"id"`
@@ -56,7 +56,7 @@ type AdminAccountInfo struct {
 	InvitedByAccountID string `json:"invited_by_account_id"`
 }
 
-// AdminReportInfo represents the *admin* view of a report. See here: https://docs.joinmastodon.org/entities/admin-report/
+// AdminReportInfo models the admin view of a report.
 type AdminReportInfo struct {
 	// The ID of the report in the database.
 	ID string `json:"id"`
diff --git a/internal/api/model/announcement.go b/internal/api/model/announcement.go
index eeb4b8720..fd686242b 100644
--- a/internal/api/model/announcement.go
+++ b/internal/api/model/announcement.go
@@ -18,20 +18,46 @@
 
 package model
 
-// Announcement represents an admin/moderator announcement for local users. See here: https://docs.joinmastodon.org/entities/announcement/
+// Announcement models an admin announcement for the instance.
+//
+// swagger:model announcement
 type Announcement struct {
-	ID          string                 `json:"id"`
-	Content     string                 `json:"content"`
-	StartsAt    string                 `json:"starts_at"`
-	EndsAt      string                 `json:"ends_at"`
-	AllDay      bool                   `json:"all_day"`
-	PublishedAt string                 `json:"published_at"`
-	UpdatedAt   string                 `json:"updated_at"`
-	Published   bool                   `json:"published"`
-	Read        bool                   `json:"read"`
-	Mentions    []Mention              `json:"mentions"`
-	Statuses    []Status               `json:"statuses"`
-	Tags        []Tag                  `json:"tags"`
-	Emojis      []Emoji                `json:"emoji"`
-	Reactions   []AnnouncementReaction `json:"reactions"`
+	// The ID of the announcement.
+	// example: 01FC30T7X4TNCZK0TH90QYF3M4
+	ID string `json:"id"`
+	// The body of the announcement.
+	// Should be HTML formatted.
+	// example: <p>This is an announcement. No malarky.</p>
+	Content string `json:"content"`
+	// When the announcement should begin to be displayed (ISO 8601 Datetime).
+	// If the announcement has no start time, this will be omitted or empty.
+	// example: 2021-07-30T09:20:25+00:00
+	StartsAt string `json:"starts_at"`
+	// When the announcement should stop being displayed (ISO 8601 Datetime).
+	// If the announcement has no end time, this will be omitted or empty.
+	// example: 2021-07-30T09:20:25+00:00
+	EndsAt string `json:"ends_at"`
+	// Announcement doesn't have begin time and end time, but begin day and end day.
+	AllDay bool `json:"all_day"`
+	// When the announcement was first published (ISO 8601 Datetime).
+	// example: 2021-07-30T09:20:25+00:00
+	PublishedAt string `json:"published_at"`
+	// When the announcement was last updated (ISO 8601 Datetime).
+	// example: 2021-07-30T09:20:25+00:00
+	UpdatedAt string `json:"updated_at"`
+	// Announcement is 'published', ie., visible to users.
+	// Announcements that are not published should be shown only to admins.
+	Published bool `json:"published"`
+	// Requesting account has seen this announcement.
+	Read bool `json:"read"`
+	// Mentions this announcement contains.
+	Mentions []Mention `json:"mentions"`
+	// Statuses contained in this announcement.
+	Statuses []Status `json:"statuses"`
+	// Tags used in this announcement.
+	Tags []Tag `json:"tags"`
+	// Emojis used in this announcement.
+	Emojis []Emoji `json:"emoji"`
+	// Reactions to this announcement.
+	Reactions []AnnouncementReaction `json:"reactions"`
 }
diff --git a/internal/api/model/announcementreaction.go b/internal/api/model/announcementreaction.go
index 81118fef0..c84a5b365 100644
--- a/internal/api/model/announcementreaction.go
+++ b/internal/api/model/announcementreaction.go
@@ -18,16 +18,24 @@
 
 package model
 
-// AnnouncementReaction represents a user reaction to admin/moderator announcement. See here: https://docs.joinmastodon.org/entities/announcementreaction/
+// AnnouncementReaction models a user reaction to an announcement.
+//
+// swagger:model announcementReaction
 type AnnouncementReaction struct {
 	// The emoji used for the reaction. Either a unicode emoji, or a custom emoji's shortcode.
+	// example: blobcat_uwu
 	Name string `json:"name"`
 	// The total number of users who have added this reaction.
+	// example: 5
 	Count int `json:"count"`
-	// Whether the authorized user has added this reaction to the announcement.
+	// This reaction belongs to the account viewing it.
 	Me bool `json:"me"`
-	// A link to the custom emoji.
+	// Web link to the image of the custom emoji.
+	// Empty for unicode emojis.
+	// example: https://example.org/custom_emojis/original/blobcat_uwu.png
 	URL string `json:"url,omitempty"`
-	// A link to a non-animated version of the custom emoji.
+	// Web link to a non-animated image of the custom emoji.
+	// Empty for unicode emojis.
+	// example: https://example.org/custom_emojis/statuc/blobcat_uwu.png
 	StaticURL string `json:"static_url,omitempty"`
 }
diff --git a/internal/api/model/application.go b/internal/api/model/application.go
index 6f949ec3e..2b663f54b 100644
--- a/internal/api/model/application.go
+++ b/internal/api/model/application.go
@@ -18,8 +18,7 @@
 
 package model
 
-// Application represents an api Application, as defined here.
-// Primarily, application is used for allowing apps like Tusky etc to connect to Mastodon on behalf of a user.
+// Application models an api application.
 //
 // swagger:model application
 type Application struct {
@@ -43,18 +42,30 @@ type Application struct {
 	VapidKey string `json:"vapid_key,omitempty"`
 }
 
-// ApplicationCreateRequest represents a POST request to https://example.org/api/v1/apps.
-// See here: https://docs.joinmastodon.org/methods/apps/
-// And here: https://docs.joinmastodon.org/client/token/
+// ApplicationCreateRequest models app create parameters.
+//
+// swagger:parameters appCreate
 type ApplicationCreateRequest struct {
-	// A name for your application
+	// The name of the application.
+	//
+	// in: formData
+	// required: true
 	ClientName string `form:"client_name" json:"client_name" xml:"client_name" binding:"required"`
 	// Where the user should be redirected after authorization.
-	// To display the authorization code to the user instead of redirecting
-	// to a web page, use urn:ietf:wg:oauth:2.0:oob in this parameter.
+	//
+	// To display the authorization code to the user instead of redirecting to a web page, use `urn:ietf:wg:oauth:2.0:oob` in this parameter.
+	//
+	// in: formData
+	// required: true
 	RedirectURIs string `form:"redirect_uris" json:"redirect_uris" xml:"redirect_uris" binding:"required"`
-	// Space separated list of scopes. If none is provided, defaults to read.
+	// Space separated list of scopes.
+	//
+	// If no scopes are provided, defaults to `read`.
+	//
+	// in: formData
 	Scopes string `form:"scopes" json:"scopes" xml:"scopes"`
-	// A URL to the homepage of your app
+	// A URL to the web page of the app (optional).
+	//
+	// in: formData
 	Website string `form:"website" json:"website" xml:"website"`
 }
diff --git a/internal/api/model/attachment.go b/internal/api/model/attachment.go
index 3242d8a7f..07167dc4f 100644
--- a/internal/api/model/attachment.go
+++ b/internal/api/model/attachment.go
@@ -20,33 +20,50 @@ package model
 
 import "mime/multipart"
 
-// AttachmentRequest represents the form data parameters submitted by a client during a media upload request.
-// See: https://docs.joinmastodon.org/methods/statuses/media/
+// AttachmentRequest models media attachment creation parameters.
+//
+// swagger: ignore
 type AttachmentRequest struct {
-	File        *multipart.FileHeader `form:"file" binding:"required"`
-	Description string                `form:"description"`
-	Focus       string                `form:"focus"`
+	// Media file.
+	File *multipart.FileHeader `form:"file" binding:"required"`
+	// Description of the media file. Optional.
+	// This will be used as alt-text for users of screenreaders etc.
+	// example: This is an image of some kittens, they are very cute and fluffy.
+	Description string `form:"description"`
+	// Focus of the media file. Optional.
+	// If present, it should be in the form of two comma-separated floats between -1 and 1.
+	// example: -0.5,0.565
+	Focus string `form:"focus"`
 }
 
-// AttachmentUpdateRequest represents the form data parameters submitted by a client during a media update/PUT request.
-// See: https://docs.joinmastodon.org/methods/statuses/media/
+// AttachmentUpdateRequest models an update request for an attachment.
+//
+// swagger:ignore
 type AttachmentUpdateRequest struct {
+	// Description of the media file.
+	// This will be used as alt-text for users of screenreaders etc.
+	// allowEmptyValue: true
 	Description *string `form:"description" json:"description" xml:"description"`
-	Focus       *string `form:"focus" json:"focus" xml:"focus"`
+	// Focus of the media file.
+	// If present, it should be in the form of two comma-separated floats between -1 and 1.
+	// allowEmptyValue: true
+	Focus *string `form:"focus" json:"focus" xml:"focus"`
 }
 
-// Attachment represents the object returned to a client after a successful media upload request.
+// Attachment models a media attachment.
 //
 // swagger:model attachment
 type Attachment struct {
 	// The ID of the attachment.
+	// example: 01FC31DZT1AYWDZ8XTCRWRBYRK
 	ID string `json:"id"`
 	// The type of the attachment.
-	// 	unknown = unsupported or unrecognized file type.
-	// 	image = Static image.
-	// 	gifv = Looping, soundless animation.
-	// 	video = Video clip.
-	// 	audio = Audio track.
+	// enum:
+	//   - unknown
+	//   - image
+	//   - gifv
+	//   - video
+	//   - audio
 	// example: image
 	Type string `json:"type"`
 	// The location of the original full-size attachment.
@@ -64,6 +81,7 @@ type Attachment struct {
 	// example: https://some-other-server.org/attachments/small/ahhhhh.jpeg
 	PreviewRemoteURL string `json:"preview_remote_url,omitempty"`
 	// A shorter URL for the attachment.
+	// Not currently used.
 	TextURL string `json:"text_url,omitempty"`
 	// Metadata for this attachment.
 	Meta MediaMeta `json:"meta,omitempty"`
@@ -75,42 +93,88 @@ type Attachment struct {
 	Blurhash string `json:"blurhash,omitempty"`
 }
 
-// MediaMeta describes the returned media
+// MediaMeta models media metadata.
+// This can be metadata about an image, an audio file, video, etc.
 //
 // swagger:model mediaMeta
 type MediaMeta struct {
-	Length        string          `json:"length,omitempty"`
-	Duration      float32         `json:"duration,omitempty"`
-	FPS           uint16          `json:"fps,omitempty"`
-	Size          string          `json:"size,omitempty"`
-	Width         int             `json:"width,omitempty"`
-	Height        int             `json:"height,omitempty"`
-	Aspect        float32         `json:"aspect,omitempty"`
-	AudioEncode   string          `json:"audio_encode,omitempty"`
-	AudioBitrate  string          `json:"audio_bitrate,omitempty"`
-	AudioChannels string          `json:"audio_channels,omitempty"`
-	Original      MediaDimensions `json:"original"`
-	Small         MediaDimensions `json:"small,omitempty"`
-	Focus         MediaFocus      `json:"focus,omitempty"`
+	Length string `json:"length,omitempty"`
+	// Duration of the media in seconds.
+	// Only set for video and audio.
+	// example: 5.43
+	Duration float32 `json:"duration,omitempty"`
+	// Framerate of the media.
+	// Only set for video and gifs.
+	// example: 30
+	FPS uint16 `json:"fps,omitempty"`
+	// Size of the media, in the format `[width]x[height]`.
+	// Not set for audio.
+	// example: 1920x1080
+	Size string `json:"size,omitempty"`
+	// Width of the media in pixels.
+	// Not set for audio.
+	// example: 1920
+	Width int `json:"width,omitempty"`
+	// Height of the media in pixels.
+	// Not set for audio.
+	// example: 1080
+	Height int `json:"height,omitempty"`
+	// Aspect ratio of the media.
+	// Equal to width / height.
+	// example: 1.777777778
+	Aspect        float32 `json:"aspect,omitempty"`
+	AudioEncode   string  `json:"audio_encode,omitempty"`
+	AudioBitrate  string  `json:"audio_bitrate,omitempty"`
+	AudioChannels string  `json:"audio_channels,omitempty"`
+	// Dimensions of the original media.
+	Original MediaDimensions `json:"original"`
+	// Dimensions of the thumbnail/small version of the media.
+	Small MediaDimensions `json:"small,omitempty"`
+	// Focus data for the media.
+	Focus MediaFocus `json:"focus,omitempty"`
 }
 
-// MediaFocus describes the focal point of a piece of media. It should be returned to the caller as part of MediaMeta.
+// MediaFocus models the focal point of a piece of media.
 //
 // swagger:model mediaFocus
 type MediaFocus struct {
-	X float32 `json:"x"` // should be between -1 and 1
-	Y float32 `json:"y"` // should be between -1 and 1
+	// x position of the focus
+	// should be between -1 and 1
+	X float32 `json:"x"`
+	// y position of the focus
+	// should be between -1 and 1
+	Y float32 `json:"y"`
 }
 
-// MediaDimensions describes the physical properties of a piece of media. It should be returned to the caller as part of MediaMeta.
+// MediaDimensions models detailed properties of a piece of media.
 //
 // swagger:model mediaDimensions
 type MediaDimensions struct {
-	Width     int     `json:"width,omitempty"`
-	Height    int     `json:"height,omitempty"`
-	FrameRate string  `json:"frame_rate,omitempty"`
-	Duration  float32 `json:"duration,omitempty"`
-	Bitrate   int     `json:"bitrate,omitempty"`
-	Size      string  `json:"size,omitempty"`
-	Aspect    float32 `json:"aspect,omitempty"`
+	// Width of the media in pixels.
+	// Not set for audio.
+	// example: 1920
+	Width int `json:"width,omitempty"`
+	// Height of the media in pixels.
+	// Not set for audio.
+	// example: 1080
+	Height int `json:"height,omitempty"`
+	// Framerate of the media.
+	// Only set for video and gifs.
+	// example: 30
+	FrameRate string `json:"frame_rate,omitempty"`
+	// Duration of the media in seconds.
+	// Only set for video and audio.
+	// example: 5.43
+	Duration float32 `json:"duration,omitempty"`
+	// Bitrate of the media in bits per second.
+	// example: 1000000
+	Bitrate int `json:"bitrate,omitempty"`
+	// Size of the media, in the format `[width]x[height]`.
+	// Not set for audio.
+	// example: 1920x1080
+	Size string `json:"size,omitempty"`
+	// Aspect ratio of the media.
+	// Equal to width / height.
+	// example: 1.777777778
+	Aspect float32 `json:"aspect,omitempty"`
 }
diff --git a/internal/api/model/card.go b/internal/api/model/card.go
index 46807a735..7442fa9cb 100644
--- a/internal/api/model/card.go
+++ b/internal/api/model/card.go
@@ -32,11 +32,11 @@ type Card struct {
 	// example: Is water wet? We're not sure. In this article, we ask an expert...
 	Description string `json:"description"`
 	// The type of the preview card.
-	//    String (Enumerable, oneOf)
-	//    link = Link OEmbed
-	//    photo = Photo OEmbed
-	//    video = Video OEmbed
-	//    rich = iframe OEmbed. Not currently accepted, so won't show up in practice.
+	// enum:
+	// - link
+	// - photo
+	// - video
+	// - rich
 	// example: link
 	Type string `json:"type"`
 	// The author of the original resource.
diff --git a/internal/api/model/context.go b/internal/api/model/context.go
index d0979319b..66e17b185 100644
--- a/internal/api/model/context.go
+++ b/internal/api/model/context.go
@@ -18,7 +18,9 @@
 
 package model
 
-// Context represents the tree around a given status. Used for reconstructing threads of statuses. See: https://docs.joinmastodon.org/entities/context/
+// Context models the tree around a given status.
+//
+// swagger:model statusContext
 type Context struct {
 	// Parents in the thread.
 	Ancestors []Status `json:"ancestors"`
diff --git a/internal/api/model/instance.go b/internal/api/model/instance.go
index c534de2d0..93c541d53 100644
--- a/internal/api/model/instance.go
+++ b/internal/api/model/instance.go
@@ -20,60 +20,77 @@ package model
 
 import "mime/multipart"
 
-// Instance represents the software instance of Mastodon running on this domain. See https://docs.joinmastodon.org/entities/instance/
+// Instance models information about this or another instance.
+//
+// swagger:model instance
 type Instance struct {
-	// REQUIRED
-
-	// The domain name of the instance.
+	// The URI of the instance.
+	// example: https://example.org
 	URI string `json:"uri,omitempty"`
-	// The title of the website.
+	// The title of the instance.
+	// example: GoToSocial Example Instance
 	Title string `json:"title,omitempty"`
-	// Admin-defined description of the Mastodon site.
+	// Description of the instance.
+	//
+	// Should be HTML formatted, but might be plaintext.
+	//
+	// This should be displayed on the 'about' page for an instance.
 	Description string `json:"description"`
-	// A shorter description defined by the admin.
+	// A shorter description of the instance.
+	//
+	// Should be HTML formatted, but might be plaintext.
+	//
+	// This should be displayed on the instance splash/landing page.
 	ShortDescription string `json:"short_description"`
-	// An email that may be contacted for any inquiries.
+	// An email address that may be used for inquiries.
+	// example: admin@example.org
 	Email string `json:"email"`
-	// The version of Mastodon installed on the instance.
+	// The version of GoToSocial installed on the instance.
+	//
+	// This will contain at least a semantic version number.
+	//
+	// It may also contain, after a space, the short git commit ID of the running software.
+	//
+	// example: 0.1.1 cb85f65
 	Version string `json:"version"`
-	// Primary langauges of the website and its staff.
+	// Primary language of the instance.
+	// example: en
 	Languages []string `json:"languages,omitempty"`
-	// Whether registrations are enabled.
+	// New account registrations are enabled on this instance.
 	Registrations bool `json:"registrations"`
-	// Whether registrations require moderator approval.
+	// New account registrations require admin approval.
 	ApprovalRequired bool `json:"approval_required"`
-	// Whether invites are enabled.
+	// Invites are enabled on this instance.
 	InvitesEnabled bool `json:"invites_enabled"`
-	// URLs of interest for clients apps.
+	// URLs of interest for client applications.
 	URLS *InstanceURLs `json:"urls,omitempty"`
-	// Statistics about how much information the instance contains.
+	// Statistics about the instance: number of posts, accounts, etc.
 	Stats map[string]int `json:"stats,omitempty"`
-	// Banner image for the website.
+	// URL of the instance avatar/banner image.
+	// example: https://example.org/files/instance/thumbnail.jpeg
 	Thumbnail string `json:"thumbnail"`
-	// A user that can be contacted, as an alternative to email.
+	// Contact account for the instance.
 	ContactAccount *Account `json:"contact_account,omitempty"`
-	// What's the maximum allowed length of a post on this instance?
-	// This is provided for compatibility with Tusky.
+	// Maximum allowed length of a post on this instance, in characters.
+	//
+	// This is provided for compatibility with Tusky and other apps.
+	//
+	// example: 5000
 	MaxTootChars uint `json:"max_toot_chars"`
 }
 
-// InstanceURLs represents URLs necessary for successfully connecting to the instance as a user. See https://docs.joinmastodon.org/entities/instance/
+// InstanceURLs models instance-relevant URLs for client application consumption.
+//
+// swagger:model instanceURLs
 type InstanceURLs struct {
-	// Websockets address for push streaming.
+	// Websockets address for status and notification streaming.
+	// example: wss://example.org
 	StreamingAPI string `json:"streaming_api"`
 }
 
-// InstanceStats represents some public-facing stats about the instance. See https://docs.joinmastodon.org/entities/instance/
-type InstanceStats struct {
-	// Users registered on this instance.
-	UserCount int `json:"user_count"`
-	// Statuses authored by users on instance.
-	StatusCount int `json:"status_count"`
-	// Domains federated with this instance.
-	DomainCount int `json:"domain_count"`
-}
-
-// InstanceSettingsUpdateRequest is the form to be parsed on a PATCH to /api/v1/instance
+// InstanceSettingsUpdateRequest models an instance update request.
+//
+// swagger:ignore
 type InstanceSettingsUpdateRequest struct {
 	// Title to use for the instance. Max 40 characters.
 	Title *string `form:"title" json:"title" xml:"title"`
diff --git a/internal/api/model/poll.go b/internal/api/model/poll.go
index c6bffbe29..a925be8fd 100644
--- a/internal/api/model/poll.go
+++ b/internal/api/model/poll.go
@@ -51,19 +51,24 @@ type Poll struct {
 type PollOptions struct {
 	// The text value of the poll option. String.
 	Title string `json:"title"`
-	// The number of received votes for this option. Number, or null if results are not published yet.
+	// The number of received votes for this option.
+	// Number, or null if results are not published yet.
 	VotesCount int `json:"votes_count,omitempty"`
 }
 
-// PollRequest represents a mastodon-api poll attached to a status POST request, as defined here: https://docs.joinmastodon.org/methods/statuses/
-// It should be used at the path https://example.org/api/v1/statuses
+// PollRequest models a request to create a poll.
+//
+// swagger:parameters createStatus
 type PollRequest struct {
-	// Array of possible answers. If provided, media_ids cannot be used, and poll[expires_in] must be provided.
-	Options []string `form:"options"`
-	// Duration the poll should be open, in seconds. If provided, media_ids cannot be used, and poll[options] must be provided.
-	ExpiresIn int `form:"expires_in"`
-	// Allow multiple choices?
-	Multiple bool `form:"multiple"`
-	// Hide vote counts until the poll ends?
-	HideTotals bool `form:"hide_totals"`
+	// Array of possible answers.
+	// If provided, media_ids cannot be used, and poll[expires_in] must be provided.
+	// name: poll[options]
+	Options []string `form:"options" json:"options" xml:"options"`
+	// Duration the poll should be open, in seconds.
+	// If provided, media_ids cannot be used, and poll[options] must be provided.
+	ExpiresIn int `form:"expires_in" json:"expires_in" xml:"expires_in"`
+	// Allow multiple choices on this poll.
+	Multiple bool `form:"multiple" json:"multiple" xml:"multiple"`
+	// Hide vote counts until the poll ends.
+	HideTotals bool `form:"hide_totals" json:"hide_totals" xml:"hide_totals"`
 }
diff --git a/internal/api/model/search.go b/internal/api/model/search.go
index ba282f6f1..6287dba0e 100644
--- a/internal/api/model/search.go
+++ b/internal/api/model/search.go
@@ -18,33 +18,72 @@
 
 package model
 
-// SearchQuery corresponds to search parameters as submitted through the client API.
-// See https://docs.joinmastodon.org/methods/search/
+// SearchQuery models a search request.
+//
+// swagger:parameters searchGet
 type SearchQuery struct {
-	// If provided, statuses returned will be authored only by this account
-	AccountID string
-	// Return results older than this id
-	MaxID string
-	// Return results immediately newer than this id
-	MinID string
-	// Enum(accounts, hashtags, statuses)
-	Type string
-	// Filter out unreviewed tags? Defaults to false. Use true when trying to find trending tags.
-	ExcludeUnreviewed bool
-	// The search query
-	Query string
-	// Attempt WebFinger lookup. Defaults to false.
-	Resolve bool
-	// Maximum number of results to load, per type. Defaults to 20. Max 40.
-	Limit int
-	// Offset in search results. Used for pagination. Defaults to 0.
-	Offset int
-	// Only include accounts that the user is following. Defaults to false.
-	Following bool
+	// If type is `statuses`, then statuses returned will be authored only by this account.
+	//
+	// in: query
+	AccountID string `json:"account_id"`
+	// Return results *older* than this id.
+	//
+	// The entry with this ID will not be included in the search results.
+	// in: query
+	MaxID string `json:"max_id"`
+	// Return results *newer* than this id.
+	//
+	// The entry with this ID will not be included in the search results.
+	// in: query
+	MinID string `json:"min_id"`
+	// Type of the search query to perform.
+	//
+	// Must be one of: `accounts`, `hashtags`, `statuses`.
+	//
+	// enum:
+	// - accounts
+	// - hashtags
+	// - statuses
+	// required: true
+	// in: query
+	Type string `json:"type"`
+	// Filter out tags that haven't been reviewed and approved by an instance admin.
+	//
+	// default: false
+	// in: query
+	ExcludeUnreviewed bool `json:"exclude_unreviewed"`
+	// String to use as a search query.
+	//
+	// For accounts, this should be in the format `@someaccount@some.instance.com`, or the format `https://some.instance.com/@someaccount`
+	//
+	// For a status, this can be in the format: `https://some.instance.com/@someaccount/SOME_ID_OF_A_STATUS`
+	//
+	// required: true
+	// in: query
+	Query string `json:"q"`
+	// Attempt to resolve the query by performing a remote webfinger lookup, if the query includes a remote host.
+	// default: false
+	Resolve bool `json:"resolve"`
+	// Maximum number of results to load, per type.
+	// default: 20
+	// minimum: 1
+	// maximum: 40
+	// in: query
+	Limit int `json:"limit"`
+	// Offset for paginating search results.
+	//
+	// default: 0
+	// in: query
+	Offset int `json:"offset"`
+	// Only include accounts that the searching account is following.
+	// default: false
+	// in: query
+	Following bool `json:"following"`
 }
 
-// SearchResult corresponds to a search result, containing accounts, statuses, and hashtags.
-// See https://docs.joinmastodon.org/methods/search/
+// SearchResult models a search result.
+//
+// swagger:model searchResult
 type SearchResult struct {
 	Accounts []Account `json:"accounts"`
 	Statuses []Status  `json:"statuses"`
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.