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'

1 files changed, 79 insertions, 40 deletions

diff --git a/internal/api/model/account.go b/internal/api/model/account.go
index ba5ac567a..1e02e38ec 100644
--- a/internal/api/model/account.go
+++ b/internal/api/model/account.go
@@ -23,104 +23,139 @@ import (
 	"net"
 )
 
-// Account represents a mastodon-api Account object, as described here: https://docs.joinmastodon.org/entities/account/
+// Account represents a fediverse account of some kind, either a remote one or one on this instance.
+//
+// swagger:model account
 type Account struct {
-	// The account id
+	// The account id.
+	// example: 01FBVD42CQ3ZEEVMW180SBX03B
 	ID string `json:"id"`
 	// The username of the account, not including domain.
+	// example: some_user
 	Username string `json:"username"`
-	// The Webfinger account URI. Equal to username for local users, or username@domain for remote users.
+	// The account URI as discovered via webfinger.
+	// Equal to username for local users, or username@domain for remote users.
+	// example: some_user@example.org
 	Acct string `json:"acct"`
-	// The profile's display name.
+	// The account's display name.
+	// example: big jeff (he/him)
 	DisplayName string `json:"display_name"`
-	// Whether the account manually approves follow requests.
+	// Account manually approves follow requests.
 	Locked bool `json:"locked"`
-	// Whether the account has opted into discovery features such as the profile directory.
+	// Account has opted into discovery features such as the profile directory.
 	Discoverable bool `json:"discoverable,omitempty"`
-	// A presentational flag. Indicates that the account may perform automated actions, may not be monitored, or identifies as a robot.
+	// Account identifies as a bot.
 	Bot bool `json:"bot"`
-	// When the account was created. (ISO 8601 Datetime)
+	// When the account was created (ISO 8601 Datetime).
+	// example: 2021-07-30T09:20:25+00:00
 	CreatedAt string `json:"created_at"`
-	// The profile's bio / description.
+	// Bio/description of this account.
 	Note string `json:"note"`
-	// The location of the user's profile page.
+	// Web location of the account's profile page.
+	// example: https://example.org/@some_user
 	URL string `json:"url"`
-	// An image icon that is shown next to statuses and in the profile.
+	// Web location of the account's avatar.
+	// example: https://example.org/media/some_user/avatar/original/avatar.jpeg
 	Avatar string `json:"avatar"`
-	// A static version of the avatar. Equal to avatar if its value is a static image; different if avatar is an animated GIF.
+	// Web location of a static version of the account's avatar.
+	// Only relevant when the account's main avatar is a video or a gif.
+	// example: https://example.org/media/some_user/avatar/static/avatar.png
 	AvatarStatic string `json:"avatar_static"`
-	// An image banner that is shown above the profile and in profile cards.
+	// Web location of the account's header image.
+	// example: https://example.org/media/some_user/header/original/header.jpeg
 	Header string `json:"header"`
-	// A static version of the header. Equal to header if its value is a static image; different if header is an animated GIF.
+	// Web location of a static version of the account's header.
+	// Only relevant when the account's main header is a video or a gif.
+	// example: https://example.org/media/some_user/header/static/header.png
 	HeaderStatic string `json:"header_static"`
-	//  The reported followers of this profile.
+	// Number of accounts following this account, according to our instance.
 	FollowersCount int `json:"followers_count"`
-	// The reported follows of this profile.
+	// Number of account's followed by this account, according to our instance.
 	FollowingCount int `json:"following_count"`
-	// How many statuses are attached to this account.
+	// Number of statuses posted by this account, according to our instance.
 	StatusesCount int `json:"statuses_count"`
-	// When the most recent status was posted. (ISO 8601 Datetime)
+	// When the account's most recent status was posted (ISO 8601 Datetime).
+	// example: 2021-07-30T09:20:25+00:00
 	LastStatusAt string `json:"last_status_at"`
-	// Custom emoji entities to be used when rendering the profile. If none, an empty array will be returned.
+	// Array of custom emojis used in this account's note or display name.
 	Emojis []Emoji `json:"emojis"`
-	// Additional metadata attached to a profile as name-value pairs.
+	// Additional metadata attached to this account's profile.
 	Fields []Field `json:"fields"`
-	// An extra entity returned when an account is suspended.
+	// Account has been suspended by our instance.
 	Suspended bool `json:"suspended,omitempty"`
-	// When a timed mute will expire, if applicable. (ISO 8601 Datetime)
+	// If this account has been muted, when will the mute expire (ISO 8601 Datetime).
+	// example: 2021-07-30T09:20:25+00:00
 	MuteExpiresAt string `json:"mute_expires_at,omitempty"`
-	// An extra entity to be used with API methods to verify credentials and update credentials.
+	// Extra profile information. Shown only if the requester owns the account being requested.
 	Source *Source `json:"source,omitempty"`
 }
 
 // AccountCreateRequest represents the form submitted during a POST request to /api/v1/accounts.
-// See https://docs.joinmastodon.org/methods/accounts/
+//
+// swagger:model accountCreateRequest
 type AccountCreateRequest struct {
 	// Text that will be reviewed by moderators if registrations require manual approval.
 	Reason string `form:"reason" json:"reason" xml:"reason"`
-	// The desired username for the account
+	// The desired username for the account.
+	// swagger:parameters
+	// pattern: [a-z0-9_]{2,64}
+	// example: a_valid_username
+	// required: true
 	Username string `form:"username" json:"username" xml:"username" binding:"required"`
-	// The email address to be used for login
+	// The email address to be used for login.
+	// swagger:parameters
+	// example: someone@wherever.com
+	// required: true
 	Email string `form:"email" json:"email" xml:"email" binding:"required"`
-	// The password to be used for login
+	// The password to be used for login. This will be hashed before storage.
+	// swagger:parameters
+	// example: some_really_really_really_strong_password
+	// required: true
 	Password string `form:"password" json:"password" xml:"password" binding:"required"`
-	// Whether the user agrees to the local rules, terms, and policies.
-	// These should be presented to the user in order to allow them to consent before setting this parameter to TRUE.
+	// The user agrees to the terms, conditions, and policies of the instance.
+	// swagger:parameters
+	// required: true
 	Agreement bool `form:"agreement"  json:"agreement" xml:"agreement" binding:"required"`
-	// The language of the confirmation email that will be sent
+	// The language of the confirmation email that will be sent.
+	// swagger:parameters
+	// example: en
+	// Required: true
 	Locale string `form:"locale" json:"locale" xml:"locale" binding:"required"`
-	// The IP of the sign up request, will not be parsed from the form but must be added manually
+	// The IP of the sign up request, will not be parsed from the form.
+	// swagger:parameters
+	// swagger:ignore
 	IP net.IP `form:"-"`
 }
 
 // UpdateCredentialsRequest represents the form submitted during a PATCH request to /api/v1/accounts/update_credentials.
-// See https://docs.joinmastodon.org/methods/accounts/
+// swagger:ignore
 type UpdateCredentialsRequest struct {
-	// Whether the account should be shown in the profile directory.
+	// Account should be made discoverable and shown in the profile directory (if enabled).
 	Discoverable *bool `form:"discoverable" json:"discoverable" xml:"discoverable"`
-	// Whether the account has a bot flag.
+	// Account is flagged as a bot.
 	Bot *bool `form:"bot" json:"bot" xml:"bot"`
-	// The display name to use for the profile.
+	// The display name to use for the account.
 	DisplayName *string `form:"display_name" json:"display_name" xml:"display_name"`
-	// The account bio.
+	// Bio/description of this account.
 	Note *string `form:"note" json:"note" xml:"note"`
-	// Avatar image encoded using multipart/form-data
+	// Avatar image encoded using multipart/form-data.
 	Avatar *multipart.FileHeader `form:"avatar" json:"avatar" xml:"avatar"`
 	// Header image encoded using multipart/form-data
 	Header *multipart.FileHeader `form:"header" json:"header" xml:"header"`
-	// Whether manual approval of follow requests is required.
+	// Require manual approval of follow requests.
 	Locked *bool `form:"locked" json:"locked" xml:"locked"`
-	// New Source values for this account
+	// New Source values for this account.
 	Source *UpdateSource `form:"source" json:"source" xml:"source"`
 	// Profile metadata name and value
 	FieldsAttributes *[]UpdateField `form:"fields_attributes" json:"fields_attributes" xml:"fields_attributes"`
 }
 
 // UpdateSource is to be used specifically in an UpdateCredentialsRequest.
+// swagger:ignore
 type UpdateSource struct {
 	// Default post privacy for authored statuses.
 	Privacy *string `form:"privacy" json:"privacy" xml:"privacy"`
-	// Whether to mark authored statuses as sensitive by default.
+	// Mark authored statuses as sensitive by default.
 	Sensitive *bool `form:"sensitive" json:"sensitive" xml:"sensitive"`
 	// Default language to use for authored statuses. (ISO 6391)
 	Language *string `form:"language" json:"language" xml:"language"`
@@ -128,6 +163,8 @@ type UpdateSource struct {
 
 // UpdateField is to be used specifically in an UpdateCredentialsRequest.
 // By default, max 4 fields and 255 characters per property/value.
+//
+// swagger:model updateField
 type UpdateField struct {
 	// Name of the field
 	Name *string `form:"name" json:"name" xml:"name"`
@@ -136,6 +173,8 @@ type UpdateField struct {
 }
 
 // AccountFollowRequest is for parsing requests at /api/v1/accounts/:id/follow
+//
+// swagger:model accountFollowRequest
 type AccountFollowRequest struct {
 	// ID of the account to follow request
 	// This should be a URL parameter not a form field