From 6bd26ff4c4d655e26adcf43d9331e9a3efe1329a Mon Sep 17 00:00:00 2001 From: Tobi Smethurst <31960611+tsmethurst@users.noreply.github.com> Date: Sat, 31 Jul 2021 23:17:39 +0200 Subject: [PATCH] more swagger docs + other changes (#125) * more swagger docs + other changes * go fmt --- README.md | 13 +- docs/api/swagger.yaml | 197 ++++++++++++++++++ docs/configuration/basics.md | 1 - docs/configuration/general.md | 2 + docs/configuration/overview.md | 3 + docs/installation_guide/binary.md | 3 + docs/installation_guide/docker.md | 2 +- .../installation_guide/quick_and_dirty.md | 32 +-- docs/{installation_guide => }/license.md | 0 .../api/client/admin/domainblockcreate.go | 84 +++++++- .../api/client/admin/domainblockdelete.go | 34 +++ internal/api/client/admin/domainblockget.go | 34 +++ internal/api/client/admin/domainblocksget.go | 40 ++++ internal/api/client/admin/emojicreate.go | 43 ++++ internal/api/model/emoji.go | 1 + 15 files changed, 465 insertions(+), 24 deletions(-) delete mode 100644 docs/configuration/basics.md create mode 100644 docs/configuration/overview.md create mode 100644 docs/installation_guide/binary.md rename GETTINGSTARTED.md => docs/installation_guide/quick_and_dirty.md (90%) rename docs/{installation_guide => }/license.md (100%) diff --git a/README.md b/README.md index 7e11a8ac6..839c5fab5 100644 --- a/README.md +++ b/README.md @@ -12,11 +12,13 @@ GoToSocial provides a lightweight, customizable, and safety-focused entryway int With GoToSocial, you can keep in touch with your friends, post, read, and share images and articles, without being tracked or advertised to. +Documentation is at [docs.gotosocial.org](https://docs.gotosocial.org). You can skip straight to the API documentation [here](https://docs.gotosocial.org/en/latest/api/swagger/). + ## Features ### Federation -Because GoToSocial uses the [ActivityPub](https://activitypub.rocks/) protocol, you can Keep in touch not only with people on your home server, but with people all over the [Fediverse](https://en.wikipedia.org/wiki/Fediverse), seamlessly! +Because GoToSocial uses the [ActivityPub](https://activitypub.rocks/) protocol, you can hang out not just with people on your home server, but with people all over the [Fediverse](https://en.wikipedia.org/wiki/Fediverse), seamlessly. ### Mastodon API compatible @@ -95,7 +97,7 @@ Because the server implementation is as generic and flexible/configurable as pos Work began on the project around February 2021, and the project is still in prerelease. -At this point, GoToSocial is already deployable and very useable, and it federates cleanly with most other Fediverse servers. +At this point, GoToSocial is already deployable and very useable, and it federates cleanly with most other Fediverse servers (not yet all). For a detailed view on what's implemented and what's not, and progress made towards a first v0.1.0 (beta) release, see [here](./PROGRESS.md). @@ -103,11 +105,11 @@ For a detailed view on what's implemented and what's not, and progress made towa Proper documentation for running and maintaining GoToSocial will be forthcoming in the first release. -For now (if you want to run it pre-alpha, like a beast), check out the [quick and dirty getting started guide](./GETTINGSTARTED.md). +For now (if you want to run it pre-alpha, like a beast), check out the [quick and dirty getting started guide](https://docs.gotosocial.org/installation_guide/quick_and_dirty/). ## Contact -For questions and comments, you can reach out to tobi on the Fediverse [here](https://ondergrond.org/@dumpsterqueer), mail [admin@gotosocial.org](mailto:admin@gotosocial.org), or [join our Matrix channel](https://matrix.to/#/#gotosocial:superseriousbusiness.org) at `#gotosocial:superseriousbusiness.org`. +For questions and comments, you can [join our Matrix channel](https://matrix.to/#/#gotosocial:superseriousbusiness.org) at `#gotosocial:superseriousbusiness.org`. This is the quickest way to reach the devs. You can also mail [admin@gotosocial.org](mailto:admin@gotosocial.org). For bugs and feature requests, please check to see if there's [already an issue](https://github.com/superseriousbusiness/gotosocial/issues), and if not, open one or use one of the above channels to make a request (if you don't have a Github account). @@ -123,7 +125,6 @@ The following libraries and frameworks are used by GoToSocial, with gratitude * [gin-contrib/static](https://github.com/gin-contrib/static); Gin static page middleware. [MIT License](https://spdx.org/licenses/MIT.html) * [go-fed/activity](https://github.com/go-fed/activity); Golang ActivityPub/ActivityStreams library. [BSD-3-Clause License](https://spdx.org/licenses/BSD-3-Clause.html). * [go-fed/httpsig](https://github.com/go-fed/httpsig); secure HTTP signature library. [BSD-3-Clause License](https://spdx.org/licenses/BSD-3-Clause.html). -* [russross/blackfriday](https://github.com/russross/blackfriday); markdown parsing for statuses. [Simplified BSD License](https://spdx.org/licenses/BSD-2-Clause.html). * [go-pg/pg](https://github.com/go-pg/pg); Postgres ORM library. [BSD-2-Clause License](https://spdx.org/licenses/BSD-2-Clause.html). * [google/uuid](https://github.com/google/uuid); UUID generation. [BSD-3-Clause License](https://spdx.org/licenses/BSD-3-Clause.html) * [gorilla/websocket](https://github.com/gorilla/websocket); Websocket connectivity. [BSD-2-Clause License](https://spdx.org/licenses/BSD-2-Clause.html). @@ -132,10 +133,12 @@ The following libraries and frameworks are used by GoToSocial, with gratitude * [mvdan/xurls](https://github.com/mvdan/xurls); URL parsing regular expressions. [BSD-3-Clause License](https://spdx.org/licenses/BSD-3-Clause.html). * [nfnt/resize](https://github.com/nfnt/resize); convenient image resizing. [ISC License](https://spdx.org/licenses/ISC.html). * [oklog/ulid](https://github.com/oklog/ulid); sequential, database-friendly ID generation. [Apache-2.0 License](https://spdx.org/licenses/Apache-2.0.html). +* [russross/blackfriday](https://github.com/russross/blackfriday); markdown parsing for statuses. [Simplified BSD License](https://spdx.org/licenses/BSD-2-Clause.html). * [sirupsen/logrus](https://github.com/sirupsen/logrus); logging. [MIT License](https://spdx.org/licenses/MIT.html). * [stretchr/testify](https://github.com/stretchr/testify); test framework. [MIT License](https://spdx.org/licenses/MIT.html). * [superseriousbusiness/exifremove](https://github.com/superseriousbusiness/exifremove) forked from [scottleedavis/go-exif-remove](https://github.com/scottleedavis/go-exif-remove); EXIF data removal. [MIT License](https://spdx.org/licenses/MIT.html). * [superseriousbusiness/oauth2](https://github.com/superseriousbusiness/oauth2) forked from [go-oauth2/oauth2](https://github.com/go-oauth2/oauth2); oauth server framework and token handling. [MIT License](https://spdx.org/licenses/MIT.html). +* [go-swagger/go-swagger](https://github.com/go-swagger/go-swagger); Swagger OpenAPI spec generation. [Apache-2.0 License](https://spdx.org/licenses/Apache-2.0.html). * [urfave/cli](https://github.com/urfave/cli); command-line interface framework. [MIT License](https://spdx.org/licenses/MIT.html). * [wagslane/go-password-validator](https://github.com/wagslane/go-password-validator); password strength validation. [MIT License](https://spdx.org/licenses/MIT.html). diff --git a/docs/api/swagger.yaml b/docs/api/swagger.yaml index dc359389f..c281a052b 100644 --- a/docs/api/swagger.yaml +++ b/docs/api/swagger.yaml @@ -1449,6 +1449,203 @@ paths: summary: Verify a token by returning account details pertaining to it. tags: - accounts + /api/v1/admin/custom_emojis: + post: + consumes: + - multipart/form-data + operationId: emojiCreate + parameters: + - 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. + example: blobcat_uwu + in: formData + name: shortcode + pattern: \w{2,30} + type: string + - description: A jpeg, png, or gif image of the emoji. + in: formData + name: domains + type: file + produces: + - application/json + responses: + "200": + description: The newly-created emoji. + schema: + $ref: '#/definitions/emoji' + "400": + description: bad request + "403": + description: forbidden + security: + - OAuth2 Bearer: + - admin + summary: Upload and create a new instance emoji. + tags: + - admin + /api/v1/admin/domain_blocks: + get: + operationId: domainBlocksGet + parameters: + - 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 + name: export + type: boolean + produces: + - application/json + responses: + "200": + description: All domain blocks currently in place. + schema: + items: + $ref: '#/definitions/domainBlock' + type: array + "400": + description: bad request + "403": + description: forbidden + "404": + description: not found + security: + - OAuth2 Bearer: + - admin + summary: View all domain blocks currently in place. + tags: + - admin + patch: + consumes: + - multipart/form-data + description: |- + 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"}]` + operationId: domainBlockCreate + parameters: + - 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. + in: query + name: import + type: boolean + - description: |- + JSON-formatted list of domain blocks to import. + This is only used if 'import' is set to true. + in: formData + name: domains + type: file + - description: |- + Single domain to block. + Used only if 'import' is not true. + example: example.org + in: formData + name: domain + type: string + - 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. + in: formData + name: obfuscate + type: boolean + - 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. + example: harassment, transphobia + in: formData + name: public_comment + type: string + - 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. + example: harassment, transphobia, and some stuff only other admins need to + know about + in: formData + name: private_comment + type: string + produces: + - application/json + responses: + "200": + description: "The newly created domain block, if import != true.\nNote that + if a list has been imported, then an `array` of\nnewly created domain + blocks will be returned instead. " + schema: + $ref: '#/definitions/domainBlock' + "400": + description: bad request + "403": + description: forbidden + security: + - OAuth2 Bearer: + - admin + summary: Create one or more domain blocks, from a string or a file. + tags: + - admin + /api/v1/admin/domain_blocks/{id}: + delete: + operationId: domainBlockDelete + parameters: + - description: The id of the domain block. + in: path + name: id + required: true + type: string + produces: + - application/json + responses: + "200": + description: The domain block that was just deleted. + schema: + $ref: '#/definitions/domainBlock' + "400": + description: bad request + "403": + description: forbidden + "404": + description: not found + security: + - OAuth2 Bearer: + - admin + summary: Delete domain block with the given ID. + tags: + - admin + get: + operationId: domainBlockGet + parameters: + - description: The id of the domain block. + in: path + name: id + required: true + type: string + produces: + - application/json + responses: + "200": + description: The requested domain block. + schema: + $ref: '#/definitions/domainBlock' + "400": + description: bad request + "403": + description: forbidden + "404": + description: not found + security: + - OAuth2 Bearer: + - admin + summary: View domain block with the given ID. + tags: + - admin schemes: - https - http diff --git a/docs/configuration/basics.md b/docs/configuration/basics.md deleted file mode 100644 index a67dacc2f..000000000 --- a/docs/configuration/basics.md +++ /dev/null @@ -1 +0,0 @@ -# How to Manage Configuration diff --git a/docs/configuration/general.md b/docs/configuration/general.md index 23d342b49..ea60a311b 100644 --- a/docs/configuration/general.md +++ b/docs/configuration/general.md @@ -1 +1,3 @@ # General + +TODO diff --git a/docs/configuration/overview.md b/docs/configuration/overview.md new file mode 100644 index 000000000..4c7d803a7 --- /dev/null +++ b/docs/configuration/overview.md @@ -0,0 +1,3 @@ +# Overview + +TODO diff --git a/docs/installation_guide/binary.md b/docs/installation_guide/binary.md new file mode 100644 index 000000000..6642810aa --- /dev/null +++ b/docs/installation_guide/binary.md @@ -0,0 +1,3 @@ +# Binary Installation + +TODO diff --git a/docs/installation_guide/docker.md b/docs/installation_guide/docker.md index 532ffe839..f03a46842 100644 --- a/docs/installation_guide/docker.md +++ b/docs/installation_guide/docker.md @@ -1,3 +1,3 @@ # Docker -Installing with Docker.... +TODO diff --git a/GETTINGSTARTED.md b/docs/installation_guide/quick_and_dirty.md similarity index 90% rename from GETTINGSTARTED.md rename to docs/installation_guide/quick_and_dirty.md index de4cb5201..2a61e4c99 100644 --- a/GETTINGSTARTED.md +++ b/docs/installation_guide/quick_and_dirty.md @@ -1,12 +1,12 @@ -# Getting Started +# Quick and Dirty -## Quick and Dirty +This is the quick and dirty getting started guide. It's not recommended to run GtS like this in production, but if you want to quickly get a server up and running, this is a good way to do it. -### 1: Domain Name +## 1: Domain Name Get a domain name -- [Namecheap](https://www.namecheap.com/) is a good place to do this, but you can use any domain name registrar that lets you manage your own DNS. -### 2: VPS +## 2: VPS Spin yourself up a cheap VPS with Linux running on it, or get a homeserver ready with Ubuntu Server or something similar. @@ -14,11 +14,11 @@ Spin yourself up a cheap VPS with Linux running on it, or get a homeserver ready This guide won't go into running [UFW](https://www.digitalocean.com/community/tutorials/how-to-set-up-a-firewall-with-ufw-on-ubuntu-18-04) and [Fail2Ban](https://linuxize.com/post/install-configure-fail2ban-on-ubuntu-20-04/) but you absolutely should do that. Leave ports `443` and `80` open. -### 3: DNS +## 3: DNS Point your domain name towards the server you just spun up. -### 4: Postgres +## 4: Postgres Install [Postgres](https://www.postgresql.org/download/) on your server and run it. @@ -28,7 +28,7 @@ If you have [Docker](https://docs.docker.com/engine/install/ubuntu/) installed o docker run -d --network host --user postgres -e POSTGRES_PASSWORD=some_password postgres ``` -### 5: Build the Binary +## 5: Build the Binary On your local machine (not your server), with Go installed, clone the GoToSocial repository, and build the binary with the provided build script: @@ -42,7 +42,7 @@ If you need to build for a different architecture other than the one you're runn GOARCH=arm64 ./build.sh ``` -### 6: Prepare VPS +## 6: Prepare VPS On the VPS or your homeserver, make the directory that GoToSocial will run from, and the directory it will use as storage: @@ -50,7 +50,7 @@ On the VPS or your homeserver, make the directory that GoToSocial will run from, mkdir /gotosocial && mkdir /gotosocial/storage ``` -### 7: Copy Binary +## 7: Copy Binary Copy your binary from your local machine onto the VPS, using something like the following command (where `example.org` is the domain you set up in step 1): @@ -60,7 +60,7 @@ scp ./gotosocial root@example.org:/gotosocial/gotosocial Replace `root` with whatever user you're actually running on your remote server (you wouldn't run as root right? ;). -### 8: Copy Web Dir +## 8: Copy Web Dir GoToSocial uses some web templates and static assets, so you need to copy these over to your VPS as well (where `example.org` is the domain you set up in step 1): @@ -68,7 +68,7 @@ GoToSocial uses some web templates and static assets, so you need to copy these scp -r ./web root@example.org:/gotosocial/ ``` -### 9: Run the Binary +## 9: Run the Binary Everything is in place now. @@ -88,11 +88,11 @@ The server should now start up and you should be able to access the splash page Note that for this example we're assuming that we're allowed to run on port 443 (standard https port), and that nothing else is running on this port. -### 10: Create and confirm your user +## 10: Create and confirm your user You can use the GoToSocial binary to also create, confirm, and promote your user account. -#### Create +### Create Run the following command to create a new account: @@ -102,7 +102,7 @@ Run the following command to create a new account: In the above command, replace `example.org` with your domain, `some_username` with your desired username, `some_email@whatever.org` with the email address you want to associate with your account, and `SOME_PASSWORD` with a secure password. -#### Confirm +### Confirm Run the following command to confirm the account you just created: @@ -112,7 +112,7 @@ Run the following command to confirm the account you just created: Replace `example.org` with your domain and `some_username` with the username of the account you just created. -#### Promote +### Promote If you want your user to have admin rights, you can promote them using a similar command: @@ -122,6 +122,6 @@ If you want your user to have admin rights, you can promote them using a similar Replace `example.org` with your domain and `some_username` with the username of the account you just created. -### 11. Login! +## 11. Login! You should now be able to log in to your instance using the email address and password of the account you just created. We recommend using [Pinafore](https://pinafore.social) or Tusky for this. diff --git a/docs/installation_guide/license.md b/docs/license.md similarity index 100% rename from docs/installation_guide/license.md rename to docs/license.md 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.