more swagger docs + other changes (#125)

* more swagger docs + other changes

* go fmt

6 files changed, 235 insertions, 1 deletions

diff --git a/internal/api/client/admin/domainblockcreate.go b/internal/api/client/admin/domainblockcreate.go
index 29436721c..8b9071c7c 100644
--- a/internal/api/client/admin/domainblockcreate.go
+++ b/internal/api/client/admin/domainblockcreate.go
@@ -12,7 +12,89 @@ import (
 	"github.com/superseriousbusiness/gotosocial/internal/oauth"
 )
 
-// DomainBlocksPOSTHandler deals with the creation of a new domain block.
+// DomainBlocksPOSTHandler deals with the creation of one or more domain blocks.
+//
+// swagger:operation PATCH /api/v1/admin/domain_blocks domainBlockCreate
+//
+// Create one or more domain blocks, from a string or a file.
+//
+// Note that you have two options when using this endpoint: either you can set 'import' to true
+// and upload a file containing multiple domain blocks, JSON-formatted, or you can leave import as
+// false, and just add one domain block.
+//
+// The format of the json file should be something like: `[{"domain":"example.org"},{"domain":"whatever.com","public_comment":"they smell"}]`
+//
+// ---
+// tags:
+// - admin
+//
+// consumes:
+// - multipart/form-data
+//
+// produces:
+// - application/json
+//
+// parameters:
+// - name: import
+//   in: query
+//   description: |-
+//     Signal that a list of domain blocks is being imported as a file.
+//     If set to true, then 'domains' must be present as a JSON-formatted file.
+//     If set to false, then 'domains' will be ignored, and 'domain' must be present.
+//   type: boolean
+// - name: domains
+//   in: formData
+//   description: |-
+//     JSON-formatted list of domain blocks to import.
+//     This is only used if 'import' is set to true.
+//   type: file
+// - name: domain
+//   in: formData
+//   description: |-
+//     Single domain to block.
+//     Used only if 'import' is not true.
+//   type: string
+//   example: example.org
+// - name: obfuscate
+//   in: formData
+//   description: |-
+//     Obfuscate the name of the domain when serving it publicly.
+//     Eg., 'example.org' becomes something like 'ex***e.org'.
+//     Used only if 'import' is not true.
+//   type: boolean
+// - name: public_comment
+//   in: formData
+//   description: |-
+//     Public comment about this domain block.
+//     Will be displayed alongside the domain block if you choose to share blocks.
+//     Used only if 'import' is not true.
+//   type: string
+//   example: "harassment, transphobia"
+// - name: private_comment
+//   in: formData
+//   description: |-
+//     Private comment about this domain block. Will only be shown to other admins, so this
+//     is a useful way of internally keeping track of why a certain domain ended up blocked.
+//     Used only if 'import' is not true.
+//   type: string
+//   example: "harassment, transphobia, and some stuff only other admins need to know about"
+//
+// security:
+// - OAuth2 Bearer:
+//   - admin
+//
+// responses:
+//   '200':
+//     description: |-
+//       The newly created domain block, if import != true.
+//       Note that if a list has been imported, then an `array` of
+//       newly created domain blocks will be returned instead.
+//     schema:
+//       "$ref": "#/definitions/domainBlock"
+//   '403':
+//      description: forbidden
+//   '400':
+//      description: bad request
 func (m *Module) DomainBlocksPOSTHandler(c *gin.Context) {
 	l := m.log.WithFields(logrus.Fields{
 		"func":        "DomainBlocksPOSTHandler",
diff --git a/internal/api/client/admin/domainblockdelete.go b/internal/api/client/admin/domainblockdelete.go
index d8f4586f9..8b773a5a9 100644
--- a/internal/api/client/admin/domainblockdelete.go
+++ b/internal/api/client/admin/domainblockdelete.go
@@ -9,6 +9,40 @@ import (
 )
 
 // DomainBlockDELETEHandler deals with the delete of an existing domain block.
+//
+// swagger:operation DELETE /api/v1/admin/domain_blocks/{id} domainBlockDelete
+//
+// Delete domain block with the given ID.
+//
+// ---
+// tags:
+// - admin
+//
+// produces:
+// - application/json
+//
+// parameters:
+// - name: id
+//   type: string
+//   description: The id of the domain block.
+//   in: path
+//   required: true
+//
+// security:
+// - OAuth2 Bearer:
+//   - admin
+//
+// responses:
+//   '200':
+//     description: The domain block that was just deleted.
+//     schema:
+//       "$ref": "#/definitions/domainBlock"
+//   '403':
+//      description: forbidden
+//   '400':
+//      description: bad request
+//   '404':
+//      description: not found
 func (m *Module) DomainBlockDELETEHandler(c *gin.Context) {
 	l := m.log.WithFields(logrus.Fields{
 		"func":        "DomainBlockDELETEHandler",
diff --git a/internal/api/client/admin/domainblockget.go b/internal/api/client/admin/domainblockget.go
index 009794f8a..5fd48ba23 100644
--- a/internal/api/client/admin/domainblockget.go
+++ b/internal/api/client/admin/domainblockget.go
@@ -10,6 +10,40 @@ import (
 )
 
 // DomainBlockGETHandler returns one existing domain block, identified by its id.
+//
+// swagger:operation GET /api/v1/admin/domain_blocks/{id} domainBlockGet
+//
+// View domain block with the given ID.
+//
+// ---
+// tags:
+// - admin
+//
+// produces:
+// - application/json
+//
+// parameters:
+// - name: id
+//   type: string
+//   description: The id of the domain block.
+//   in: path
+//   required: true
+//
+// security:
+// - OAuth2 Bearer:
+//   - admin
+//
+// responses:
+//   '200':
+//     description: The requested domain block.
+//     schema:
+//       "$ref": "#/definitions/domainBlock"
+//   '403':
+//      description: forbidden
+//   '400':
+//      description: bad request
+//   '404':
+//      description: not found
 func (m *Module) DomainBlockGETHandler(c *gin.Context) {
 	l := m.log.WithFields(logrus.Fields{
 		"func":        "DomainBlockGETHandler",
diff --git a/internal/api/client/admin/domainblocksget.go b/internal/api/client/admin/domainblocksget.go
index 1e873a302..70f1f5d08 100644
--- a/internal/api/client/admin/domainblocksget.go
+++ b/internal/api/client/admin/domainblocksget.go
@@ -10,6 +10,46 @@ import (
 )
 
 // DomainBlocksGETHandler returns a list of all existing domain blocks.
+//
+// swagger:operation GET /api/v1/admin/domain_blocks domainBlocksGet
+//
+// View all domain blocks currently in place.
+//
+// ---
+// tags:
+// - admin
+//
+// produces:
+// - application/json
+//
+// parameters:
+// - name: export
+//   type: boolean
+//   description: |-
+//     If set to true, then each entry in the returned list of domain blocks will only consist of
+//     the fields 'domain' and 'public_comment'. This is perfect for when you want to save and share
+//     a list of all the domains you have blocked on your instance, so that someone else can easily import them,
+//     but you don't need them to see the database IDs of your blocks, or private comments etc.
+//   in: query
+//   required: false
+//
+// security:
+// - OAuth2 Bearer:
+//   - admin
+//
+// responses:
+//   '200':
+//     description: All domain blocks currently in place.
+//     schema:
+//       type: array
+//       items:
+//         "$ref": "#/definitions/domainBlock"
+//   '403':
+//      description: forbidden
+//   '400':
+//      description: bad request
+//   '404':
+//      description: not found
 func (m *Module) DomainBlocksGETHandler(c *gin.Context) {
 	l := m.log.WithFields(logrus.Fields{
 		"func":        "DomainBlocksGETHandler",
diff --git a/internal/api/client/admin/emojicreate.go b/internal/api/client/admin/emojicreate.go
index 0e60db65f..94e6ecf7a 100644
--- a/internal/api/client/admin/emojicreate.go
+++ b/internal/api/client/admin/emojicreate.go
@@ -31,6 +31,49 @@ import (
 	"github.com/superseriousbusiness/gotosocial/internal/util"
 )
 
+// emojiCreateRequest handles the creation of a new instance emoji.
+//
+// swagger:operation POST /api/v1/admin/custom_emojis emojiCreate
+//
+// Upload and create a new instance emoji.
+//
+// ---
+// tags:
+// - admin
+//
+// consumes:
+// - multipart/form-data
+//
+// produces:
+// - application/json
+//
+// parameters:
+// - name: shortcode
+//   in: formData
+//   description: |-
+//     The code to use for the emoji, which will be used by instance denizens to select it.
+//     This must be unique on the instance.
+//   type: string
+//   pattern: \w{2,30}
+//   example: blobcat_uwu
+// - name: domains
+//   in: formData
+//   description: A png or gif image of the emoji. Animated pngs work too!
+//   type: file
+//
+// security:
+// - OAuth2 Bearer:
+//   - admin
+//
+// responses:
+//   '200':
+//     description: The newly-created emoji.
+//     schema:
+//       "$ref": "#/definitions/emoji"
+//   '403':
+//      description: forbidden
+//   '400':
+//      description: bad request
 func (m *Module) emojiCreatePOSTHandler(c *gin.Context) {
 	l := m.log.WithFields(logrus.Fields{
 		"func":        "emojiCreatePOSTHandler",
diff --git a/internal/api/model/emoji.go b/internal/api/model/emoji.go
index c1f81bf17..7f55038f7 100644
--- a/internal/api/model/emoji.go
+++ b/internal/api/model/emoji.go
@@ -42,6 +42,7 @@ type Emoji struct {
 }
 
 // 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.