From 58dddd86e0ddbb0c6aa54506dcef162321babfbb Mon Sep 17 00:00:00 2001
From: Tobi Smethurst <31960611+tsmethurst@users.noreply.github.com>
Date: Sat, 31 Jul 2021 17:49:59 +0200
Subject: 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'
---
 internal/api/client/account/accountcreate.go |  44 +++++++++-
 internal/api/client/account/accountget.go    |  38 ++++++++-
 internal/api/client/account/accountupdate.go |  76 +++++++++++++++--
 internal/api/client/account/accountverify.go |  28 ++++++-
 internal/api/client/account/block.go         |  35 ++++++++
 internal/api/client/account/follow.go        |  35 ++++++++
 internal/api/client/account/followers.go     |  37 +++++++++
 internal/api/client/account/following.go     |  37 +++++++++
 internal/api/client/account/relationships.go |  39 +++++++++
 internal/api/client/account/statuses.go      |  74 +++++++++++++++--
 internal/api/client/account/unblock.go       |  35 ++++++++
 internal/api/client/account/unfollow.go      |  35 ++++++++
 internal/api/model/account.go                | 119 ++++++++++++++++++---------
 internal/api/model/activity.go               |  31 -------
 internal/api/model/application.go            |  23 ++++--
 internal/api/model/attachment.go             |  26 ++++--
 internal/api/model/card.go                   |  18 ++--
 internal/api/model/domainblock.go            |  34 ++++++--
 internal/api/model/emoji.go                  |  20 +++--
 internal/api/model/field.go                  |  17 ++--
 internal/api/model/mention.go                |  15 ++--
 internal/api/model/poll.go                   |  11 ++-
 internal/api/model/relationship.go           |  27 +++---
 internal/api/model/status.go                 |  67 +++++++++------
 internal/api/model/tag.go                    |   8 +-
 internal/api/model/token.go                  |  15 ++--
 26 files changed, 758 insertions(+), 186 deletions(-)
 delete mode 100644 internal/api/model/activity.go

(limited to 'internal/api')

diff --git a/internal/api/client/account/accountcreate.go b/internal/api/client/account/accountcreate.go
index b53d8c412..e7b05fcc6 100644
--- a/internal/api/client/account/accountcreate.go
+++ b/internal/api/client/account/accountcreate.go
@@ -32,13 +32,53 @@ import (
 
 // AccountCreatePOSTHandler handles create account requests, validates them,
 // and puts them in the database if they're valid.
-// It should be served as a POST at /api/v1/accounts
+//
+// swagger:operation POST /api/v1/accounts accountCreate
+//
+// Create a new account using an application token.
+//
+// ---
+// tags:
+// - accounts
+//
+// consumes:
+// - application/json
+// - application/xml
+// - application/x-www-form-urlencoded
+// - multipart/form-data
+//
+// produces:
+// - application/json
+//
+// parameters:
+// - name: Account Create Request
+//   in: body
+//   schema:
+//     "$ref": "#/definitions/accountCreateRequest"
+//
+// security:
+// - OAuth2 Application:
+//   - write:accounts
+//
+// responses:
+//   '200':
+//     description: "An OAuth2 access token for the newly-created account."
+//     schema:
+//       "$ref": "#/definitions/oauthToken"
+//   '401':
+//      description: unauthorized
+//   '400':
+//      description: bad request
+//   '404':
+//      description: not found
+//   '500':
+//      description: internal error
 func (m *Module) AccountCreatePOSTHandler(c *gin.Context) {
 	l := m.log.WithField("func", "accountCreatePOSTHandler")
 	authed, err := oauth.Authed(c, true, true, false, false)
 	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
 	}
 
diff --git a/internal/api/client/account/accountget.go b/internal/api/client/account/accountget.go
index 5ca17a167..ff7c1a485 100644
--- a/internal/api/client/account/accountget.go
+++ b/internal/api/client/account/accountget.go
@@ -25,12 +25,42 @@ import (
 	"github.com/superseriousbusiness/gotosocial/internal/oauth"
 )
 
-// AccountGETHandler serves the account information held by the server in response to a GET
-// request. It should be served as a GET at /api/v1/accounts/:id.
+// AccountGETHandler returns info about the given account.
 //
-// See: https://docs.joinmastodon.org/methods/accounts/
+// swagger:operation GET /api/v1/accounts/{id} accountGet
+//
+// Get information about an account with the given ID.
+//
+// ---
+// tags:
+// - accounts
+//
+// produces:
+// - application/json
+//
+// parameters:
+// - name: id
+//   type: string
+//   description: The id of the requested account.
+//   in: path
+//   required: true
+//
+// security:
+// - OAuth2 Bearer:
+//   - read:accounts
+//
+// responses:
+//   '200':
+//     schema:
+//       "$ref": "#/definitions/account"
+//   '401':
+//      description: unauthorized
+//   '400':
+//      description: bad request
+//   '404':
+//      description: not found
 func (m *Module) AccountGETHandler(c *gin.Context) {
-	authed, err := oauth.Authed(c, false, false, false, false)
+	authed, err := oauth.Authed(c, true, true, true, true)
 	if err != nil {
 		c.JSON(http.StatusUnauthorized, gin.H{"error": "unauthorized"})
 		return
diff --git a/internal/api/client/account/accountupdate.go b/internal/api/client/account/accountupdate.go
index 23a350503..6d9a3f3f9 100644
--- a/internal/api/client/account/accountupdate.go
+++ b/internal/api/client/account/accountupdate.go
@@ -29,14 +29,78 @@ import (
 // AccountUpdateCredentialsPATCHHandler allows a user to modify their account/profile settings.
 // It should be served as a PATCH at /api/v1/accounts/update_credentials
 //
-// TODO: this can be optimized massively by building up a picture of what we want the new account
-// details to be, and then inserting it all in the database at once. As it is, we do queries one-by-one
-// which is not gonna make the database very happy when lots of requests are going through.
-// This way it would also be safer because the update won't happen until *all* the fields are validated.
-// Otherwise we risk doing a partial update and that's gonna cause probllleeemmmsss.
+// swagger:operation PATCH /api/v1/accounts/update_credentials accountUpdate
+//
+// Update your account.
+//
+// ---
+// tags:
+// - accounts
+//
+// consumes:
+// - multipart/form-data
+//
+// produces:
+// - application/json
+//
+// parameters:
+// - name: discoverable
+//   in: formData
+//   description: Account should be made discoverable and shown in the profile directory (if enabled).
+//   type: boolean
+// - name: bot
+//   in: formData
+//   description: Account is flagged as a bot.
+//   type: boolean
+// - name: display_name
+//   in: formData
+//   description: The display name to use for the account.
+//   type: string
+// - name: note
+//   in: formData
+//   description: Bio/description of this account.
+//   type: string
+// - name: avatar
+//   in: formData
+//   description: Avatar of the user.
+//   type: file
+// - name: header
+//   in: formData
+//   description: Header of the user.
+//   type: file
+// - name: locked
+//   in: formData
+//   description: Require manual approval of follow requests.
+//   type: boolean
+// - name: source.privacy
+//   in: formData
+//   description: Default post privacy for authored statuses.
+//   type: string
+// - name: source.sensitive
+//   in: formData
+//   description: Mark authored statuses as sensitive by default.
+//   type: boolean
+// - name: source.language
+//   in: formData
+//   description: Default language to use for authored statuses (ISO 6391).
+//   type: string
+//
+// security:
+// - OAuth2 Bearer:
+//   - write:accounts
+//
+// responses:
+//   '200':
+//     description: "The newly updated account."
+//     schema:
+//       "$ref": "#/definitions/account"
+//   '401':
+//      description: unauthorized
+//   '400':
+//      description: bad request
 func (m *Module) AccountUpdateCredentialsPATCHHandler(c *gin.Context) {
 	l := m.log.WithField("func", "accountUpdateCredentialsPATCHHandler")
-	authed, err := oauth.Authed(c, true, false, false, true)
+	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()})
diff --git a/internal/api/client/account/accountverify.go b/internal/api/client/account/accountverify.go
index 4c62ff705..0ff61362d 100644
--- a/internal/api/client/account/accountverify.go
+++ b/internal/api/client/account/accountverify.go
@@ -27,7 +27,33 @@ import (
 
 // AccountVerifyGETHandler serves a user's account details to them IF they reached this
 // handler while in possession of a valid token, according to the oauth middleware.
-// It should be served as a GET at /api/v1/accounts/verify_credentials
+// It should be served as a GET at /api/v1/accounts/verify_credentials.
+//
+// swagger:operation GET /api/v1/accounts/verify_credentials accountVerify
+//
+// Verify a token by returning account details pertaining to it.
+//
+// ---
+// tags:
+// - accounts
+//
+// produces:
+// - application/json
+//
+// security:
+// - OAuth2 Bearer:
+//   - read:accounts
+//
+// responses:
+//   '200':
+//     schema:
+//       "$ref": "#/definitions/account"
+//   '401':
+//      description: unauthorized
+//   '400':
+//      description: bad request
+//   '404':
+//      description: not found
 func (m *Module) AccountVerifyGETHandler(c *gin.Context) {
 	l := m.log.WithField("func", "accountVerifyGETHandler")
 	authed, err := oauth.Authed(c, true, false, false, true)
diff --git a/internal/api/client/account/block.go b/internal/api/client/account/block.go
index c83837c2a..ec2ba5b2c 100644
--- a/internal/api/client/account/block.go
+++ b/internal/api/client/account/block.go
@@ -26,6 +26,41 @@ import (
 )
 
 // AccountBlockPOSTHandler handles the creation of a block from the authed account targeting the given account ID.
+//
+// swagger:operation POST /api/v1/accounts/{id}/block accountBlock
+//
+// Block account with id.
+//
+// ---
+// tags:
+// - accounts
+//
+// produces:
+// - application/json
+//
+// parameters:
+// - name: id
+//   type: string
+//   description: The id of the account to block.
+//   in: path
+//   required: true
+//
+// security:
+// - OAuth2 Bearer:
+//   - write:blocks
+//
+// responses:
+//   '200':
+//     name: account relationship
+//     description: Your relationship to this account.
+//     schema:
+//       "$ref": "#/definitions/accountRelationship"
+//   '401':
+//      description: unauthorized
+//   '400':
+//      description: bad request
+//   '404':
+//      description: not found
 func (m *Module) AccountBlockPOSTHandler(c *gin.Context) {
 	authed, err := oauth.Authed(c, true, true, true, true)
 	if err != nil {
diff --git a/internal/api/client/account/follow.go b/internal/api/client/account/follow.go
index bee41c280..a0c5213fa 100644
--- a/internal/api/client/account/follow.go
+++ b/internal/api/client/account/follow.go
@@ -27,6 +27,41 @@ import (
 )
 
 // AccountFollowPOSTHandler is the endpoint for creating a new follow request to the target account
+//
+// swagger:operation POST /api/v1/accounts/{id}/follow accountFollow
+//
+// Follow account with id.
+//
+// ---
+// tags:
+// - accounts
+//
+// produces:
+// - application/json
+//
+// parameters:
+// - name: id
+//   type: string
+//   description: The id of the account to follow.
+//   in: path
+//   required: true
+//
+// security:
+// - OAuth2 Bearer:
+//   - write:follows
+//
+// responses:
+//   '200':
+//     name: account relationship
+//     description: Your relationship to this account.
+//     schema:
+//       "$ref": "#/definitions/accountRelationship"
+//   '401':
+//      description: unauthorized
+//   '400':
+//      description: bad request
+//   '404':
+//      description: not found
 func (m *Module) AccountFollowPOSTHandler(c *gin.Context) {
 	authed, err := oauth.Authed(c, true, true, true, true)
 	if err != nil {
diff --git a/internal/api/client/account/followers.go b/internal/api/client/account/followers.go
index 3401df24c..85bb65978 100644
--- a/internal/api/client/account/followers.go
+++ b/internal/api/client/account/followers.go
@@ -26,6 +26,43 @@ import (
 )
 
 // AccountFollowersGETHandler serves the followers of the requested account, if they're visible to the requester.
+//
+// swagger:operation GET /api/v1/accounts/{id}/followers accountFollowers
+//
+// See followers of account with given id.
+//
+// ---
+// tags:
+// - accounts
+//
+// produces:
+// - application/json
+//
+// parameters:
+// - name: id
+//   type: string
+//   description: Account ID.
+//   in: path
+//   required: true
+//
+// security:
+// - OAuth2 Bearer:
+//   - read:accounts
+//
+// responses:
+//   '200':
+//     name: accounts
+//     description: Array of accounts that follow this account.
+//     schema:
+//       type: array
+//       items:
+//         "$ref": "#/definitions/account"
+//   '401':
+//      description: unauthorized
+//   '400':
+//      description: bad request
+//   '404':
+//      description: not found
 func (m *Module) AccountFollowersGETHandler(c *gin.Context) {
 	authed, err := oauth.Authed(c, true, true, true, true)
 	if err != nil {
diff --git a/internal/api/client/account/following.go b/internal/api/client/account/following.go
index f1adeac2b..e0ab2748b 100644
--- a/internal/api/client/account/following.go
+++ b/internal/api/client/account/following.go
@@ -26,6 +26,43 @@ import (
 )
 
 // AccountFollowingGETHandler serves the following of the requested account, if they're visible to the requester.
+//
+// swagger:operation GET /api/v1/accounts/{id}/following accountFollowing
+//
+// See accounts followed by given account id.
+//
+// ---
+// tags:
+// - accounts
+//
+// produces:
+// - application/json
+//
+// parameters:
+// - name: id
+//   type: string
+//   description: Account ID.
+//   in: path
+//   required: true
+//
+// security:
+// - OAuth2 Bearer:
+//   - read:accounts
+//
+// responses:
+//   '200':
+//     name: accounts
+//     description: Array of accounts that are followed by this account.
+//     schema:
+//       type: array
+//       items:
+//         "$ref": "#/definitions/account"
+//   '401':
+//      description: unauthorized
+//   '400':
+//      description: bad request
+//   '404':
+//      description: not found
 func (m *Module) AccountFollowingGETHandler(c *gin.Context) {
 	authed, err := oauth.Authed(c, true, true, true, true)
 	if err != nil {
diff --git a/internal/api/client/account/relationships.go b/internal/api/client/account/relationships.go
index fd96867ac..b0404c3a1 100644
--- a/internal/api/client/account/relationships.go
+++ b/internal/api/client/account/relationships.go
@@ -9,6 +9,45 @@ import (
 )
 
 // AccountRelationshipsGETHandler serves the relationship of the requesting account with one or more requested account IDs.
+//
+// swagger:operation GET /api/v1/accounts/relationships accountRelationships
+//
+// See your account's relationships with the given account IDs.
+//
+// ---
+// tags:
+// - accounts
+//
+// produces:
+// - application/json
+//
+// parameters:
+// - name: id
+//   type: array
+//   items:
+//     type: string
+//   description: Account IDs.
+//   in: query
+//   required: true
+//
+// security:
+// - OAuth2 Bearer:
+//   - read:accounts
+//
+// responses:
+//   '200':
+//     name: account relationships
+//     description: Array of account relationships.
+//     schema:
+//       type: array
+//       items:
+//         "$ref": "#/definitions/accountRelationship"
+//   '401':
+//      description: unauthorized
+//   '400':
+//      description: bad request
+//   '404':
+//      description: not found
 func (m *Module) AccountRelationshipsGETHandler(c *gin.Context) {
 	l := m.log.WithField("func", "AccountRelationshipsGETHandler")
 
diff --git a/internal/api/client/account/statuses.go b/internal/api/client/account/statuses.go
index c92e85cee..8e9faffcf 100644
--- a/internal/api/client/account/statuses.go
+++ b/internal/api/client/account/statuses.go
@@ -28,13 +28,75 @@ import (
 
 // AccountStatusesGETHandler serves the statuses of the requested account, if they're visible to the requester.
 //
-// Several different filters might be passed into this function in the query:
+// swagger:operation GET /api/v1/accounts/{id}/statuses accountStatuses
 //
-// 	limit -- show only limit number of statuses
-// 	exclude_replies -- exclude statuses that are a reply to another status
-// 	max_id -- the maximum ID of the status to show
-// 	pinned -- show only pinned statuses
-// 	media_only -- show only statuses that have media attachments
+// See statuses posted by the requested account.
+//
+// The statuses will be returned in descending chronological order (newest first), with sequential IDs (bigger = newer).
+//
+// ---
+// tags:
+// - accounts
+//
+// produces:
+// - application/json
+//
+// parameters:
+// - name: id
+//   type: string
+//   description: Account ID.
+//   in: path
+//   required: true
+// - name: limit
+//   type: integer
+//   description: Number of statuses to return.
+//   default: 30
+//   in: query
+//   required: false
+// - name: exclude_replies
+//   type: boolean
+//   description: Exclude statuses that are a reply to another status.
+//   default: false
+//   in: query
+//   required: false
+// - name: max_id
+//   type: string
+//   description: |-
+//     Return only statuses *OLDER* than the given max status ID.
+//     The status with the specified ID will not be included in the response.
+//   in: query
+//   required: false
+// - name: pinned_only
+//   type: boolean
+//   description: Show only pinned statuses. In other words,e xclude statuses that are not pinned to the given account ID.
+//   default: false
+//   in: query
+//   required: false
+// - name: media_only
+//   type: boolean
+//   description: Show only statuses with media attachments.
+//   default: false
+//   in: query
+//   required: false
+//
+// security:
+// - OAuth2 Bearer:
+//   - read:accounts
+//
+// responses:
+//   '200':
+//     name: statuses
+//     description: Array of statuses..
+//     schema:
+//       type: array
+//       items:
+//         "$ref": "#/definitions/status"
+//   '401':
+//      description: unauthorized
+//   '400':
+//      description: bad request
+//   '404':
+//      description: not found
 func (m *Module) AccountStatusesGETHandler(c *gin.Context) {
 	l := m.log.WithField("func", "AccountStatusesGETHandler")
 
diff --git a/internal/api/client/account/unblock.go b/internal/api/client/account/unblock.go
index 1cb959db9..60b7c766d 100644
--- a/internal/api/client/account/unblock.go
+++ b/internal/api/client/account/unblock.go
@@ -26,6 +26,41 @@ import (
 )
 
 // AccountUnblockPOSTHandler handles the removal of a block from the authed account targeting the given account ID.
+//
+// swagger:operation POST /api/v1/accounts/{id}/unblock accountUnblock
+//
+// Unblock account with ID.
+//
+// ---
+// tags:
+// - accounts
+//
+// produces:
+// - application/json
+//
+// parameters:
+// - name: id
+//   type: string
+//   description: The id of the account to unblock.
+//   in: path
+//   required: true
+//
+// security:
+// - OAuth2 Bearer:
+//   - write:blocks
+//
+// responses:
+//   '200':
+//     name: account relationship
+//     description: Your relationship to this account.
+//     schema:
+//       "$ref": "#/definitions/accountRelationship"
+//   '401':
+//      description: unauthorized
+//   '400':
+//      description: bad request
+//   '404':
+//      description: not found
 func (m *Module) AccountUnblockPOSTHandler(c *gin.Context) {
 	authed, err := oauth.Authed(c, true, true, true, true)
 	if err != nil {
diff --git a/internal/api/client/account/unfollow.go b/internal/api/client/account/unfollow.go
index 69ed72b88..ba0ab8426 100644
--- a/internal/api/client/account/unfollow.go
+++ b/internal/api/client/account/unfollow.go
@@ -26,6 +26,41 @@ import (
 )
 
 // AccountUnfollowPOSTHandler is the endpoint for removing a follow and/or follow request to the target account
+//
+// swagger:operation POST /api/v1/accounts/{id}/unfollow accountUnfollow
+//
+// Unfollow account with id.
+//
+// ---
+// tags:
+// - accounts
+//
+// produces:
+// - application/json
+//
+// parameters:
+// - name: id
+//   type: string
+//   description: The id of the account to unfollow.
+//   in: path
+//   required: true
+//
+// security:
+// - OAuth2 Bearer:
+//   - write:follows
+//
+// responses:
+//   '200':
+//     name: account relationship
+//     description: Your relationship to this account.
+//     schema:
+//       "$ref": "#/definitions/accountRelationship"
+//   '401':
+//      description: unauthorized
+//   '400':
+//      description: bad request
+//   '404':
+//      description: not found
 func (m *Module) AccountUnfollowPOSTHandler(c *gin.Context) {
 	l := m.log.WithField("func", "AccountUnfollowPOSTHandler")
 	authed, err := oauth.Authed(c, true, true, true, true)
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
diff --git a/internal/api/model/activity.go b/internal/api/model/activity.go
deleted file mode 100644
index c1736a8d6..000000000
--- a/internal/api/model/activity.go
+++ /dev/null
@@ -1,31 +0,0 @@
-/*
-   GoToSocial
-   Copyright (C) 2021 GoToSocial Authors admin@gotosocial.org
-
-   This program is free software: you can redistribute it and/or modify
-   it under the terms of the GNU Affero General Public License as published by
-   the Free Software Foundation, either version 3 of the License, or
-   (at your option) any later version.
-
-   This program is distributed in the hope that it will be useful,
-   but WITHOUT ANY WARRANTY; without even the implied warranty of
-   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-   GNU Affero General Public License for more details.
-
-   You should have received a copy of the GNU Affero General Public License
-   along with this program.  If not, see <http://www.gnu.org/licenses/>.
-*/
-
-package model
-
-// Activity represents the mastodon-api Activity type. See here: https://docs.joinmastodon.org/entities/activity/
-type Activity struct {
-	// Midnight at the first day of the week. (UNIX Timestamp as string)
-	Week string `json:"week"`
-	// Statuses created since the week began. Integer cast to string.
-	Statuses string `json:"statuses"`
-	// User logins since the week began. Integer cast as string.
-	Logins string `json:"logins"`
-	// User registrations since the week began. Integer cast as string.
-	Registrations string `json:"registrations"`
-}
diff --git a/internal/api/model/application.go b/internal/api/model/application.go
index fe9fada03..6f949ec3e 100644
--- a/internal/api/model/application.go
+++ b/internal/api/model/application.go
@@ -18,23 +18,28 @@
 
 package model
 
-// Application represents a mastodon-api Application, as defined here: https://docs.joinmastodon.org/entities/application/.
+// 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.
-// See https://docs.joinmastodon.org/methods/apps/
+//
+// swagger:model application
 type Application struct {
-	// The application ID in the db
+	// The ID of the application.
+	// example: 01FBVD42CQ3ZEEVMW180SBX03B
 	ID string `json:"id,omitempty"`
-	// The name of your application.
+	// The name of the application.
+	// example: Tusky
 	Name string `json:"name"`
-	// The website associated with your application (url)
+	// The website associated with the application (url)
+	// example: https://tusky.app
 	Website string `json:"website,omitempty"`
-	// Where the user should be redirected after authorization.
+	// Post-authorization redirect URI for the application (OAuth2).
+	// example: https://example.org/callback?some=query
 	RedirectURI string `json:"redirect_uri,omitempty"`
-	// ClientID to use when obtaining an oauth token for this application (ie., in client_id parameter of https://docs.joinmastodon.org/methods/apps/)
+	// Client ID associated with this application.
 	ClientID string `json:"client_id,omitempty"`
-	// Client secret to use when obtaining an auth token for this application (ie., in client_secret parameter of https://docs.joinmastodon.org/methods/apps/)
+	// Client secret associated with this application.
 	ClientSecret string `json:"client_secret,omitempty"`
-	// Used for Push Streaming API. Returned with POST /api/v1/apps. Equivalent to https://docs.joinmastodon.org/entities/pushsubscription/#server_key
+	// Push API key for this application.
 	VapidKey string `json:"vapid_key,omitempty"`
 }
 
diff --git a/internal/api/model/attachment.go b/internal/api/model/attachment.go
index ed53757eb..3242d8a7f 100644
--- a/internal/api/model/attachment.go
+++ b/internal/api/model/attachment.go
@@ -36,9 +36,10 @@ type AttachmentUpdateRequest struct {
 }
 
 // Attachment represents the object returned to a client after a successful media upload request.
-// See: https://docs.joinmastodon.org/methods/statuses/media/
+//
+// swagger:model attachment
 type Attachment struct {
-	// The ID of the attachment in the database.
+	// The ID of the attachment.
 	ID string `json:"id"`
 	// The type of the attachment.
 	// 	unknown = unsupported or unrecognized file type.
@@ -46,23 +47,28 @@ type Attachment struct {
 	// 	gifv = Looping, soundless animation.
 	// 	video = Video clip.
 	// 	audio = Audio track.
+	// example: image
 	Type string `json:"type"`
 	// The location of the original full-size attachment.
+	// example: https://example.org/fileserver/some_id/attachments/some_id/original/attachment.jpeg
 	URL string `json:"url"`
 	// The location of a scaled-down preview of the attachment.
+	// example: https://example.org/fileserver/some_id/attachments/some_id/small/attachment.jpeg
 	PreviewURL string `json:"preview_url"`
 	// The location of the full-size original attachment on the remote server.
+	// Only defined for instances other than our own.
+	// example: https://some-other-server.org/attachments/original/ahhhhh.jpeg
 	RemoteURL string `json:"remote_url,omitempty"`
 	// The location of a scaled-down preview of the attachment on the remote server.
+	// Only defined for instances other than our own.
+	// example: https://some-other-server.org/attachments/small/ahhhhh.jpeg
 	PreviewRemoteURL string `json:"preview_remote_url,omitempty"`
 	// A shorter URL for the attachment.
 	TextURL string `json:"text_url,omitempty"`
-	// Metadata returned by Paperclip.
-	// May contain subtrees small and original, as well as various other top-level properties.
-	// More importantly, there may be another top-level focus Hash object as of 2.3.0, with coordinates can be used for smart thumbnail cropping.
-	// See https://docs.joinmastodon.org/methods/statuses/media/#focal-points points for more.
+	// Metadata for this attachment.
 	Meta MediaMeta `json:"meta,omitempty"`
-	// Alternate text that describes what is in the media attachment, to be used for the visually impaired or when media attachments do not load.
+	// Alt text that describes what is in the media attachment.
+	// example: This is a picture of a kitten.
 	Description string `json:"description,omitempty"`
 	// A hash computed by the BlurHash algorithm, for generating colorful preview thumbnails when media has not been downloaded yet.
 	// See https://github.com/woltapp/blurhash
@@ -70,6 +76,8 @@ type Attachment struct {
 }
 
 // MediaMeta describes the returned media
+//
+// swagger:model mediaMeta
 type MediaMeta struct {
 	Length        string          `json:"length,omitempty"`
 	Duration      float32         `json:"duration,omitempty"`
@@ -87,12 +95,16 @@ type MediaMeta struct {
 }
 
 // MediaFocus describes the focal point of a piece of media. It should be returned to the caller as part of MediaMeta.
+//
+// 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
 }
 
 // MediaDimensions describes the physical properties of a piece of media. It should be returned to the caller as part of MediaMeta.
+//
+// swagger:model mediaDimensions
 type MediaDimensions struct {
 	Width     int     `json:"width,omitempty"`
 	Height    int     `json:"height,omitempty"`
diff --git a/internal/api/model/card.go b/internal/api/model/card.go
index ffa6d53e5..46807a735 100644
--- a/internal/api/model/card.go
+++ b/internal/api/model/card.go
@@ -18,15 +18,18 @@
 
 package model
 
-// Card represents a rich preview card that is generated using OpenGraph tags from a URL. See here: https://docs.joinmastodon.org/entities/card/
+// Card represents a rich preview card that is generated using OpenGraph tags from a URL.
+//
+// swagger:model card
 type Card struct {
-	// REQUIRED
-
 	// Location of linked resource.
+	// example: https://buzzfeed.com/some/fuckin/buzzfeed/article
 	URL string `json:"url"`
 	// Title of linked resource.
+	// example: Buzzfeed - Is Water Wet?
 	Title string `json:"title"`
 	// Description of preview.
+	// 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)
@@ -34,17 +37,19 @@ type Card struct {
 	//    photo = Photo OEmbed
 	//    video = Video OEmbed
 	//    rich = iframe OEmbed. Not currently accepted, so won't show up in practice.
+	// example: link
 	Type string `json:"type"`
-
-	// OPTIONAL
-
 	// The author of the original resource.
+	// example: weewee@buzzfeed.com
 	AuthorName string `json:"author_name"`
 	// A link to the author of the original resource.
+	// example: https://buzzfeed.com/authors/weewee
 	AuthorURL string `json:"author_url"`
 	// The provider of the original resource.
+	// example: Buzzfeed
 	ProviderName string `json:"provider_name"`
 	// A link to the provider of the original resource.
+	// example: https://buzzfeed.com
 	ProviderURL string `json:"provider_url"`
 	// HTML to be used for generating the preview card.
 	HTML string `json:"html"`
@@ -53,6 +58,7 @@ type Card struct {
 	// Height of preview, in pixels.
 	Height int `json:"height"`
 	// Preview thumbnail.
+	// example: https://example.org/fileserver/preview/thumb.jpg
 	Image string `json:"image"`
 	// Used for photo embeds, instead of custom html.
 	EmbedURL string `json:"embed_url"`
diff --git a/internal/api/model/domainblock.go b/internal/api/model/domainblock.go
index 66d155ad7..ad44e6b3e 100644
--- a/internal/api/model/domainblock.go
+++ b/internal/api/model/domainblock.go
@@ -21,18 +21,40 @@ package model
 import "mime/multipart"
 
 // DomainBlock represents a block on one domain
+//
+// swagger:model domainBlock
 type DomainBlock struct {
-	ID             string `json:"id,omitempty"`
-	Domain         string `form:"domain" json:"domain" validation:"required"`
-	Obfuscate      bool   `json:"obfuscate,omitempty"`
+	// The ID of the domain block.
+	// example: 01FBW21XJA09XYX51KV5JVBW0F
+	// readonly: true
+	ID string `json:"id,omitempty"`
+	// The hostname of the blocked domain.
+	// example: example.org
+	Domain string `form:"domain" json:"domain" validation:"required"`
+	// Obfuscate the domain name when serving this domain block publicly.
+	// A useful anti-harassment tool.
+	// example: false
+	Obfuscate bool `json:"obfuscate,omitempty"`
+	// Private comment for this block, visible to our instance admins only.
+	// example: they are poopoo
 	PrivateComment string `json:"private_comment,omitempty"`
-	PublicComment  string `form:"public_comment" json:"public_comment,omitempty"`
+	// Public comment for this block, visible if domain blocks are served publicly.
+	// example: they smell
+	PublicComment string `form:"public_comment" json:"public_comment,omitempty"`
+	// The ID of the subscription that created/caused this domain block.
+	// example: 01FBW25TF5J67JW3HFHZCSD23K
 	SubscriptionID string `json:"subscription_id,omitempty"`
-	CreatedBy      string `json:"created_by,omitempty"`
-	CreatedAt      string `json:"created_at,omitempty"`
+	// ID of the account that created this domain block.
+	// example: 01FBW2758ZB6PBR200YPDDJK4C
+	CreatedBy string `json:"created_by,omitempty"`
+	// Time at which this block was created (ISO 8601 Datetime).
+	// example: 2021-07-30T09:20:25+00:00
+	CreatedAt string `json:"created_at,omitempty"`
 }
 
 // DomainBlockCreateRequest is the form submitted as a POST to /api/v1/admin/domain_blocks to create a new block.
+//
+// swagger:model domainBlockCreateRequest
 type DomainBlockCreateRequest struct {
 	// A list of domains to block. Only used if import=true is specified.
 	Domains *multipart.FileHeader `form:"domains" json:"domains" xml:"domains"`
diff --git a/internal/api/model/emoji.go b/internal/api/model/emoji.go
index c2834718f..c1f81bf17 100644
--- a/internal/api/model/emoji.go
+++ b/internal/api/model/emoji.go
@@ -20,28 +20,32 @@ package model
 
 import "mime/multipart"
 
-// Emoji represents a custom emoji. See https://docs.joinmastodon.org/entities/emoji/
+// Emoji represents a custom emoji.
+//
+// swagger:model emoji
 type Emoji struct {
-	// REQUIRED
-
 	// The name of the custom emoji.
+	// example: blobcat_uwu
 	Shortcode string `json:"shortcode"`
-	// A link to the custom emoji.
+	// Web URL of the custom emoji.
+	// example: https://example.org/fileserver/emojis/blogcat_uwu.gif
 	URL string `json:"url"`
 	// A link to a static copy of the custom emoji.
+	// example: https://example.org/fileserver/emojis/blogcat_uwu.png
 	StaticURL string `json:"static_url"`
-	// Whether this Emoji should be visible in the picker or unlisted.
+	// Emoji is visible in the emoji picker of the instance.
+	// example: true
 	VisibleInPicker bool `json:"visible_in_picker"`
-
-	// OPTIONAL
-
 	// Used for sorting custom emoji in the picker.
+	// example: blobcats
 	Category string `json:"category,omitempty"`
 }
 
 // EmojiCreateRequest represents a request to create a custom emoji made through the admin API.
+// swagger:model emojiCreateRequest
 type EmojiCreateRequest struct {
 	// Desired shortcode for the emoji, without surrounding colons. This must be unique for the domain.
+	// example: blobcat_uwu
 	Shortcode string `form:"shortcode" validation:"required"`
 	// Image file to use for the emoji. Must be png or gif and no larger than 50kb.
 	Image *multipart.FileHeader `form:"image" validation:"required"`
diff --git a/internal/api/model/field.go b/internal/api/model/field.go
index 2e7662b2b..ae6b65272 100644
--- a/internal/api/model/field.go
+++ b/internal/api/model/field.go
@@ -18,16 +18,17 @@
 
 package model
 
-// Field represents a profile field as a name-value pair with optional verification. See https://docs.joinmastodon.org/entities/field/
+// Field represents a name/value pair to display on an account's profile.
+//
+// swagger:model field
 type Field struct {
-	// REQUIRED
-
-	// The key of a given field's key-value pair.
+	// The key/name of this field.
+	// example: pronouns
 	Name string `json:"name"`
-	// The value associated with the name key.
+	// The value of this field.
+	// example: they/them
 	Value string `json:"value"`
-
-	// OPTIONAL
-	// Timestamp of when the server verified a URL value for a rel="me” link. String (ISO 8601 Datetime) if value is a verified URL
+	// If this field has been verified, when did this occur? (ISO 8601 Datetime).
+	// example: 2021-07-30T09:20:25+00:00
 	VerifiedAt string `json:"verified_at,omitempty"`
 }
diff --git a/internal/api/model/mention.go b/internal/api/model/mention.go
index a7985af24..382ea3499 100644
--- a/internal/api/model/mention.go
+++ b/internal/api/model/mention.go
@@ -18,14 +18,19 @@
 
 package model
 
-// Mention represents the mastodon-api mention type, as documented here: https://docs.joinmastodon.org/entities/mention/
+// Mention represents a mention of another account.
 type Mention struct {
-	// The account id of the mentioned user.
+	// The ID of the mentioned account.
+	// example: 01FBYJHQWQZAVWFRK9PDYTKGMB
 	ID string `json:"id"`
-	// The username of the mentioned user.
+	// The username of the mentioned account.
+	// example: some_user
 	Username string `json:"username"`
-	// The location of the mentioned user's profile.
+	// The web URL of the mentioned account's profile.
+	// example: https://example.org/@some_user
 	URL string `json:"url"`
-	// The webfinger acct: URI of the mentioned user. Equivalent 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"`
 }
diff --git a/internal/api/model/poll.go b/internal/api/model/poll.go
index b00e7680a..c6bffbe29 100644
--- a/internal/api/model/poll.go
+++ b/internal/api/model/poll.go
@@ -18,12 +18,15 @@
 
 package model
 
-// Poll represents the mastodon-api poll type, as described here: https://docs.joinmastodon.org/entities/poll/
+// Poll represents a poll attached to a status.
+//
+// swagger:model poll
 type Poll struct {
 	// The ID of the poll in the database.
+	// example: 01FBYKMD1KBMJ0W6JF1YZ3VY5D
 	ID string `json:"id"`
 	// When the poll ends. (ISO 8601 Datetime), or null if the poll does not end
-	ExpiresAt string `json:"expires_at"`
+	ExpiresAt string `json:"expires_at,omitempty"`
 	// Is the poll currently expired?
 	Expired bool `json:"expired"`
 	// Does the poll allow multiple-choice answers?
@@ -42,7 +45,9 @@ type Poll struct {
 	Emojis []Emoji `json:"emojis"`
 }
 
-// PollOptions represents the current vote counts for different poll options
+// PollOptions represents the current vote counts for different poll options.
+//
+// swagger:model pollOptions
 type PollOptions struct {
 	// The text value of the poll option. String.
 	Title string `json:"title"`
diff --git a/internal/api/model/relationship.go b/internal/api/model/relationship.go
index 6e71023e2..647ff7a91 100644
--- a/internal/api/model/relationship.go
+++ b/internal/api/model/relationship.go
@@ -18,31 +18,34 @@
 
 package model
 
-// Relationship represents a relationship between accounts. See https://docs.joinmastodon.org/entities/relationship/
+// Relationship represents a relationship between accounts.
+//
+// swagger:model accountRelationship
 type Relationship struct {
 	// The account id.
+	// example: 01FBW9XGEP7G6K88VY4S9MPE1R
 	ID string `json:"id"`
-	// Are you following this user?
+	// You are following this account.
 	Following bool `json:"following"`
-	// Are you receiving this user's boosts in your home timeline?
+	// You are seeing reblogs/boosts from this account in your home timeline.
 	ShowingReblogs bool `json:"showing_reblogs"`
-	// Have you enabled notifications for this user?
+	// You are seeing notifications when this account posts.
 	Notifying bool `json:"notifying"`
-	// Are you followed by this user?
+	// This account follows you.
 	FollowedBy bool `json:"followed_by"`
-	// Are you blocking this user?
+	// You are blocking this account.
 	Blocking bool `json:"blocking"`
-	// Is this user blocking you?
+	// This account is blocking you.
 	BlockedBy bool `json:"blocked_by"`
-	// Are you muting this user?
+	// You are muting this account.
 	Muting bool `json:"muting"`
-	// Are you muting notifications from this user?
+	// You are muting notifications from this account.
 	MutingNotifications bool `json:"muting_notifications"`
-	// Do you have a pending follow request for this user?
+	// You have requested to follow this account, and the request is pending.
 	Requested bool `json:"requested"`
-	// Are you blocking this user's domain?
+	// You are blocking this account's domain.
 	DomainBlocking bool `json:"domain_blocking"`
-	// Are you featuring this user on your profile?
+	// You are featuring this account on your profile.
 	Endorsed bool `json:"endorsed"`
 	// Your note on this account.
 	Note string `json:"note"`
diff --git a/internal/api/model/status.go b/internal/api/model/status.go
index ef96568c4..919fb3e37 100644
--- a/internal/api/model/status.go
+++ b/internal/api/model/status.go
@@ -18,49 +18,62 @@
 
 package model
 
-// Status represents a mastodon-api Status type, as defined here: https://docs.joinmastodon.org/entities/status/
+// Status represents a status or post.
+//
+// swagger:model status
 type Status struct {
-	// ID of the status in the database.
+	// ID of the status.
+	// example: 01FBVD42CQ3ZEEVMW180SBX03B
 	ID string `json:"id"`
-	// The date when this status was created (ISO 8601 Datetime)
+	// The date when this status was created (ISO 8601 Datetime).
+	// example: 2021-07-30T09:20:25+00:00
 	CreatedAt string `json:"created_at"`
-	// ID of the status being replied.
+	// ID of the status being replied to.
+	// example: 01FBVD42CQ3ZEEVMW180SBX03B
 	InReplyToID string `json:"in_reply_to_id,omitempty"`
 	// ID of the account being replied to.
+	// example: 01FBVD42CQ3ZEEVMW180SBX03B
 	InReplyToAccountID string `json:"in_reply_to_account_id,omitempty"`
-	// Is this status marked as sensitive content?
+	// Status contains sensitive content.
+	// example: false
 	Sensitive bool `json:"sensitive"`
-	// Subject or summary line, below which status content is collapsed until expanded.
+	// Subject, summary, or content warning for the status.
+	// example: warning nsfw
 	SpoilerText string `json:"spoiler_text"`
 	// Visibility of this status.
+	// example: unlisted
 	Visibility Visibility `json:"visibility"`
-	// Primary language of this status. (ISO 639 Part 1 two-letter language code)
+	// Primary language of this status (ISO 639 Part 1 two-letter language code).
+	// example: en
 	Language string `json:"language"`
-	// URI of the status used for federation.
+	// ActivityPub URI of the status. Equivalent to the status's activitypub ID.
+	// example: https://example.org/users/some_user/statuses/01FBVD42CQ3ZEEVMW180SBX03B
 	URI string `json:"uri"`
-	// A link to the status's HTML representation.
+	// The status's publicly available web URL. This link will only work if the visibility of the status is 'public'.
+	// example: https://example.org/@some_user/statuses/01FBVD42CQ3ZEEVMW180SBX03B
 	URL string `json:"url"`
-	// How many replies this status has received.
+	// Number of replies to this status, according to our instance.
 	RepliesCount int `json:"replies_count"`
-	// How many boosts this status has received.
+	// Number of times this status has been boosted/reblogged, according to our instance.
 	ReblogsCount int `json:"reblogs_count"`
-	// How many favourites this status has received.
+	// Number of favourites/likes this status has received, according to our instance.
 	FavouritesCount int `json:"favourites_count"`
-	// Have you favourited this status?
+	// This status has been favourited by the account viewing it.
 	Favourited bool `json:"favourited"`
-	// Have you boosted this status?
+	// This status has been boosted/reblogged by the account viewing it.
 	Reblogged bool `json:"reblogged"`
-	// Have you muted notifications for this status's conversation?
+	// Replies to this status have been muted by the account viewing it.
 	Muted bool `json:"muted"`
-	// Have you bookmarked this status?
+	// This status has been bookmarked by the account viewing it.
 	Bookmarked bool `json:"bookmarked"`
-	// Have you pinned this status? Only appears if the status is pinnable.
+	// This status has been pinned by the account viewing it (only relevant for your own statuses).
 	Pinned bool `json:"pinned,omitempty"`
-	// HTML-encoded status content.
+	// 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 being reblogged.
+	// The status that this status is a reblog/boost of.
 	Reblog *Status `json:"reblog,omitempty"`
-	// The application used to post this status.
+	// The application used to post this status, if visible.
 	Application *Application `json:"application"`
 	// The account that authored this status.
 	Account *Account `json:"account"`
@@ -108,17 +121,21 @@ type StatusCreateRequest struct {
 	Format StatusFormat `form:"format" json:"format" xml:"format"`
 }
 
-// Visibility denotes the visibility of this status to other users
+// Visibility denotes the visibility of a status to other users.
+//
+// swagger:model statusVisibility
 type Visibility string
 
 const (
-	// VisibilityPublic means visible to everyone
+	// VisibilityPublic is visible to everyone, and will be available via the web even for nonauthenticated users.
 	VisibilityPublic Visibility = "public"
-	// VisibilityUnlisted means visible to everyone but only on home timelines or in lists
+	// VisibilityUnlisted is visible to everyone, but only on home timelines, lists, etc.
 	VisibilityUnlisted Visibility = "unlisted"
-	// VisibilityPrivate means visible to followers only
+	// VisibilityPrivate is visible only to followers of the account that posted the status.
 	VisibilityPrivate Visibility = "private"
-	// VisibilityDirect means visible only to tagged recipients
+	// VisibilityMutualsOnly is visible only to mutual followers of the account that posted the status.
+	VisibilityMutualsOnly Visibility = "mutuals_only"
+	// VisibilityDirect is visible only to accounts tagged in the status. It is equivalent to a direct message.
 	VisibilityDirect Visibility = "direct"
 )
 
diff --git a/internal/api/model/tag.go b/internal/api/model/tag.go
index f009b4cef..951f07808 100644
--- a/internal/api/model/tag.go
+++ b/internal/api/model/tag.go
@@ -18,10 +18,14 @@
 
 package model
 
-// Tag represents a hashtag used within the content of a status. See https://docs.joinmastodon.org/entities/tag/
+// Tag represents a hashtag used within the content of a status.
+//
+// swagger:model tag
 type Tag struct {
 	// The value of the hashtag after the # sign.
+	// example: helloworld
 	Name string `json:"name"`
-	// A link to the hashtag on the instance.
+	// Web link to the hashtag.
+	// example: https://example.org/tags/helloworld
 	URL string `json:"url"`
 }
diff --git a/internal/api/model/token.go b/internal/api/model/token.go
index 611ab214c..29a3c6f1d 100644
--- a/internal/api/model/token.go
+++ b/internal/api/model/token.go
@@ -18,14 +18,19 @@
 
 package model
 
-// Token represents an OAuth token used for authenticating with the API and performing actions.. See https://docs.joinmastodon.org/entities/token/
+// Token represents an OAuth token used for authenticating with the GoToSocial API and performing actions.
+//
+// swagger:model oauthToken
 type Token struct {
-	// An OAuth token to be used for authorization.
+	// Access token used for authorization.
 	AccessToken string `json:"access_token"`
-	// The OAuth token type. Mastodon uses Bearer tokens.
+	// OAuth token type. Will always be 'Bearer'.
+	// example: bearer
 	TokenType string `json:"token_type"`
-	// The OAuth scopes granted by this token, space-separated.
+	// OAuth scopes granted by this token, space-separated.
+	// example: read write admin
 	Scope string `json:"scope"`
-	// When the token was generated. (UNIX timestamp seconds)
+	// When the OAuth token was generated (UNIX timestamp seconds).
+	// example: 1627644520
 	CreatedAt int64 `json:"created_at"`
 }
-- 
cgit v1.2.3