From 0386a28b5a3c4212320e8a96ddd14c54b65a2090 Mon Sep 17 00:00:00 2001 From: Tobi Smethurst <31960611+tsmethurst@users.noreply.github.com> Date: Mon, 2 Aug 2021 19:06:44 +0200 Subject: Frodo swaggins (#126) * more swagger fun * document a whole bunch more stuff * more swagger yayyyyyyy * progress + go fmt --- internal/api/client/status/statusboost.go | 40 ++++++++++- internal/api/client/status/statusboosted_by.go | 60 ---------------- internal/api/client/status/statusboostedby.go | 95 ++++++++++++++++++++++++++ internal/api/client/status/statuscontext.go | 39 ++++++++++- internal/api/client/status/statuscreate.go | 37 +++++++++- internal/api/client/status/statusdelete.go | 39 ++++++++++- internal/api/client/status/statusfave.go | 36 +++++++++- internal/api/client/status/statusfavedby.go | 37 +++++++++- internal/api/client/status/statusget.go | 36 +++++++++- internal/api/client/status/statusunboost.go | 37 +++++++++- internal/api/client/status/statusunfave.go | 36 +++++++++- 11 files changed, 423 insertions(+), 69 deletions(-) delete mode 100644 internal/api/client/status/statusboosted_by.go create mode 100644 internal/api/client/status/statusboostedby.go (limited to 'internal/api/client/status') diff --git a/internal/api/client/status/statusboost.go b/internal/api/client/status/statusboost.go index 5521efc27..5aa7989bc 100644 --- a/internal/api/client/status/statusboost.go +++ b/internal/api/client/status/statusboost.go @@ -26,7 +26,45 @@ import ( "github.com/superseriousbusiness/gotosocial/internal/oauth" ) -// StatusBoostPOSTHandler handles boost requests against a given status ID +// StatusBoostPOSTHandler swagger:operation POST /api/v1/statuses/{id}/reblog statusReblog +// +// Reblog/boost status with the given ID. +// +// If the target status is rebloggable/boostable, it will be shared with your followers. +// This is equivalent to an activitypub 'announce' activity. +// +// --- +// tags: +// - statuses +// +// produces: +// - application/json +// +// parameters: +// - name: id +// type: string +// description: Target status ID. +// in: path +// required: true +// +// security: +// - OAuth2 Bearer: +// - write:statuses +// +// responses: +// '200': +// name: status +// description: The boost of the status. +// schema: +// "$ref": "#/definitions/status" +// '400': +// description: bad request +// '401': +// description: unauthorized +// '403': +// description: forbidden +// '404': +// description: not found func (m *Module) StatusBoostPOSTHandler(c *gin.Context) { l := m.log.WithFields(logrus.Fields{ "func": "StatusBoostPOSTHandler", diff --git a/internal/api/client/status/statusboosted_by.go b/internal/api/client/status/statusboosted_by.go deleted file mode 100644 index debcc1b22..000000000 --- a/internal/api/client/status/statusboosted_by.go +++ /dev/null @@ -1,60 +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 . -*/ - -package status - -import ( - "net/http" - - "github.com/gin-gonic/gin" - "github.com/sirupsen/logrus" - "github.com/superseriousbusiness/gotosocial/internal/oauth" -) - -// StatusBoostedByGETHandler is for serving a list of accounts that have boosted/reblogged a given status -func (m *Module) StatusBoostedByGETHandler(c *gin.Context) { - l := m.log.WithFields(logrus.Fields{ - "func": "StatusBoostedByGETHandler", - "request_uri": c.Request.RequestURI, - "user_agent": c.Request.UserAgent(), - "origin_ip": c.ClientIP(), - }) - l.Debugf("entering function") - - authed, err := oauth.Authed(c, true, true, true, true) // we don't really need an app here but we want everything else - if err != nil { - l.Errorf("error authing status boosted by request: %s", err) - c.JSON(http.StatusBadRequest, gin.H{"error": "not authed"}) - return - } - - targetStatusID := c.Param(IDKey) - if targetStatusID == "" { - c.JSON(http.StatusBadRequest, gin.H{"error": "no status id provided"}) - return - } - - mastoAccounts, err := m.processor.StatusBoostedBy(authed, targetStatusID) - if err != nil { - l.Debugf("error processing status boosted by request: %s", err) - c.JSON(http.StatusBadRequest, gin.H{"error": "bad request"}) - return - } - - c.JSON(http.StatusOK, mastoAccounts) -} diff --git a/internal/api/client/status/statusboostedby.go b/internal/api/client/status/statusboostedby.go new file mode 100644 index 000000000..260e21642 --- /dev/null +++ b/internal/api/client/status/statusboostedby.go @@ -0,0 +1,95 @@ +/* + 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 . +*/ + +package status + +import ( + "net/http" + + "github.com/gin-gonic/gin" + "github.com/sirupsen/logrus" + "github.com/superseriousbusiness/gotosocial/internal/oauth" +) + +// StatusBoostedByGETHandler swagger:operation GET /api/v1/statuses/{id}/reblogged_by statusBoostedBy +// +// View accounts that have reblogged/boosted the target status. +// +// --- +// tags: +// - statuses +// +// produces: +// - application/json +// +// parameters: +// - name: id +// type: string +// description: Target status ID. +// in: path +// required: true +// +// security: +// - OAuth2 Bearer: +// - read:accounts +// +// responses: +// '200': +// schema: +// type: array +// items: +// "$ref": "#/definitions/account" +// '400': +// description: bad request +// '401': +// description: unauthorized +// '403': +// description: forbidden +// '404': +// description: not found +func (m *Module) StatusBoostedByGETHandler(c *gin.Context) { + l := m.log.WithFields(logrus.Fields{ + "func": "StatusBoostedByGETHandler", + "request_uri": c.Request.RequestURI, + "user_agent": c.Request.UserAgent(), + "origin_ip": c.ClientIP(), + }) + l.Debugf("entering function") + + authed, err := oauth.Authed(c, true, true, true, true) // we don't really need an app here but we want everything else + if err != nil { + l.Errorf("error authing status boosted by request: %s", err) + c.JSON(http.StatusBadRequest, gin.H{"error": "not authed"}) + return + } + + targetStatusID := c.Param(IDKey) + if targetStatusID == "" { + c.JSON(http.StatusBadRequest, gin.H{"error": "no status id provided"}) + return + } + + mastoAccounts, err := m.processor.StatusBoostedBy(authed, targetStatusID) + if err != nil { + l.Debugf("error processing status boosted by request: %s", err) + c.JSON(http.StatusBadRequest, gin.H{"error": "bad request"}) + return + } + + c.JSON(http.StatusOK, mastoAccounts) +} diff --git a/internal/api/client/status/statuscontext.go b/internal/api/client/status/statuscontext.go index 83071f4a0..6e28b004e 100644 --- a/internal/api/client/status/statuscontext.go +++ b/internal/api/client/status/statuscontext.go @@ -26,7 +26,44 @@ import ( "github.com/superseriousbusiness/gotosocial/internal/oauth" ) -// StatusContextGETHandler returns the context around the given status ID. +// StatusContextGETHandler swagger:operation GET /api/v1/statuses/{id}/context statusContext +// +// Return ancestors and descendants of the given status. +// +// The returned statuses will be ordered in a thread structure, so they are suitable to be displayed in the order in which they were returned. +// +// --- +// tags: +// - statuses +// +// produces: +// - application/json +// +// parameters: +// - name: id +// type: string +// description: Target status ID. +// in: path +// required: true +// +// security: +// - OAuth2 Bearer: +// - read:statuses +// +// responses: +// '200': +// name: statuses +// description: Status context object. +// schema: +// "$ref": "#/definitions/statusContext" +// '400': +// description: bad request +// '401': +// description: unauthorized +// '403': +// description: forbidden +// '404': +// description: not found func (m *Module) StatusContextGETHandler(c *gin.Context) { l := m.log.WithFields(logrus.Fields{ "func": "StatusContextGETHandler", diff --git a/internal/api/client/status/statuscreate.go b/internal/api/client/status/statuscreate.go index 178901536..2007ba80f 100644 --- a/internal/api/client/status/statuscreate.go +++ b/internal/api/client/status/statuscreate.go @@ -30,7 +30,42 @@ import ( "github.com/superseriousbusiness/gotosocial/internal/util" ) -// StatusCreatePOSTHandler deals with the creation of new statuses +// StatusCreatePOSTHandler swagger:operation POST /api/v1/statuses statusCreate +// +// Create a new status. +// +// The parameters can also be given in the body of the request, as JSON, if the content-type is set to 'application/json'. +// The parameters can also be given in the body of the request, as XML, if the content-type is set to 'application/xml'. +// +// --- +// tags: +// - statuses +// +// consumes: +// - application/json +// - application/xml +// - application/x-www-form-urlencoded +// +// produces: +// - application/json +// +// security: +// - OAuth2 Bearer: +// - write:statuses +// +// responses: +// '200': +// description: "The newly created status." +// schema: +// "$ref": "#/definitions/status" +// '401': +// description: unauthorized +// '400': +// description: bad request +// '404': +// description: not found +// '500': +// description: internal error func (m *Module) StatusCreatePOSTHandler(c *gin.Context) { l := m.log.WithField("func", "statusCreatePOSTHandler") authed, err := oauth.Authed(c, true, true, true, true) // posting a status is serious business so we want *everything* diff --git a/internal/api/client/status/statusdelete.go b/internal/api/client/status/statusdelete.go index 5c2a1aa32..257280ce0 100644 --- a/internal/api/client/status/statusdelete.go +++ b/internal/api/client/status/statusdelete.go @@ -26,7 +26,44 @@ import ( "github.com/superseriousbusiness/gotosocial/internal/oauth" ) -// StatusDELETEHandler verifies and handles deletion of a status +// StatusDELETEHandler swagger:operation DELETE /api/v1/statuses/{id} statusDelete +// +// Delete status with the given ID. The status must belong to you. +// +// The deleted status will be returned in the response. The `text` field will contain the original text of the status as it was submitted. +// This is useful when doing a 'delete and redraft' type operation. +// +// --- +// tags: +// - statuses +// +// produces: +// - application/json +// +// parameters: +// - name: id +// type: string +// description: Target status ID. +// in: path +// required: true +// +// security: +// - OAuth2 Bearer: +// - write:statuses +// +// responses: +// '200': +// description: "The newly deleted status." +// schema: +// "$ref": "#/definitions/status" +// '400': +// description: bad request +// '401': +// description: unauthorized +// '403': +// description: forbidden +// '404': +// description: not found func (m *Module) StatusDELETEHandler(c *gin.Context) { l := m.log.WithFields(logrus.Fields{ "func": "StatusDELETEHandler", diff --git a/internal/api/client/status/statusfave.go b/internal/api/client/status/statusfave.go index 888589a8a..a76acf3d9 100644 --- a/internal/api/client/status/statusfave.go +++ b/internal/api/client/status/statusfave.go @@ -26,7 +26,41 @@ import ( "github.com/superseriousbusiness/gotosocial/internal/oauth" ) -// StatusFavePOSTHandler handles fave requests against a given status ID +// StatusFavePOSTHandler swagger:operation POST /api/v1/statuses/{id}/favourite statusFave +// +// Star/like/favourite the given status, if permitted. +// +// --- +// tags: +// - statuses +// +// produces: +// - application/json +// +// parameters: +// - name: id +// type: string +// description: Target status ID. +// in: path +// required: true +// +// security: +// - OAuth2 Bearer: +// - write:statuses +// +// responses: +// '200': +// description: "The newly faved status." +// schema: +// "$ref": "#/definitions/status" +// '400': +// description: bad request +// '401': +// description: unauthorized +// '403': +// description: forbidden +// '404': +// description: not found func (m *Module) StatusFavePOSTHandler(c *gin.Context) { l := m.log.WithFields(logrus.Fields{ "func": "StatusFavePOSTHandler", diff --git a/internal/api/client/status/statusfavedby.go b/internal/api/client/status/statusfavedby.go index 799acb7d2..a5d6e7c58 100644 --- a/internal/api/client/status/statusfavedby.go +++ b/internal/api/client/status/statusfavedby.go @@ -26,7 +26,42 @@ import ( "github.com/superseriousbusiness/gotosocial/internal/oauth" ) -// StatusFavedByGETHandler is for serving a list of accounts that have faved a given status +// StatusFavedByGETHandler swagger:operation GET /api/v1/statuses/{id}/favourited_by statusFavedBy +// +// View accounts that have faved/starred/liked the target status. +// +// --- +// tags: +// - statuses +// +// produces: +// - application/json +// +// parameters: +// - name: id +// type: string +// description: Target status ID. +// in: path +// required: true +// +// security: +// - OAuth2 Bearer: +// - read:accounts +// +// responses: +// '200': +// schema: +// type: array +// items: +// "$ref": "#/definitions/account" +// '400': +// description: bad request +// '401': +// description: unauthorized +// '403': +// description: forbidden +// '404': +// description: not found func (m *Module) StatusFavedByGETHandler(c *gin.Context) { l := m.log.WithFields(logrus.Fields{ "func": "statusGETHandler", diff --git a/internal/api/client/status/statusget.go b/internal/api/client/status/statusget.go index c6239cb36..bcca010f5 100644 --- a/internal/api/client/status/statusget.go +++ b/internal/api/client/status/statusget.go @@ -26,7 +26,41 @@ import ( "github.com/superseriousbusiness/gotosocial/internal/oauth" ) -// StatusGETHandler is for handling requests to just get one status based on its ID +// StatusGETHandler swagger:operation GET /api/v1/statuses/{id} statusGet +// +// View status with the given ID. +// +// --- +// tags: +// - statuses +// +// produces: +// - application/json +// +// parameters: +// - name: id +// type: string +// description: Target status ID. +// in: path +// required: true +// +// security: +// - OAuth2 Bearer: +// - read:statuses +// +// responses: +// '200': +// description: "The requested created status." +// schema: +// "$ref": "#/definitions/status" +// '401': +// description: unauthorized +// '400': +// description: bad request +// '404': +// description: not found +// '500': +// description: internal error func (m *Module) StatusGETHandler(c *gin.Context) { l := m.log.WithFields(logrus.Fields{ "func": "statusGETHandler", diff --git a/internal/api/client/status/statusunboost.go b/internal/api/client/status/statusunboost.go index cf6b61f52..dc42e3b62 100644 --- a/internal/api/client/status/statusunboost.go +++ b/internal/api/client/status/statusunboost.go @@ -26,7 +26,42 @@ import ( "github.com/superseriousbusiness/gotosocial/internal/oauth" ) -// StatusUnboostPOSTHandler handles unboost requests against a given status ID +// StatusUnboostPOSTHandler swagger:operation POST /api/v1/statuses/{id}/unreblog statusUnreblog +// +// Unreblog/unboost status with the given ID. +// +// --- +// tags: +// - statuses +// +// produces: +// - application/json +// +// parameters: +// - name: id +// type: string +// description: Target status ID. +// in: path +// required: true +// +// security: +// - OAuth2 Bearer: +// - write:statuses +// +// responses: +// '200': +// name: status +// description: The unboosted status. +// schema: +// "$ref": "#/definitions/status" +// '400': +// description: bad request +// '401': +// description: unauthorized +// '403': +// description: forbidden +// '404': +// description: not found func (m *Module) StatusUnboostPOSTHandler(c *gin.Context) { l := m.log.WithFields(logrus.Fields{ "func": "StatusUnboostPOSTHandler", diff --git a/internal/api/client/status/statusunfave.go b/internal/api/client/status/statusunfave.go index 94fd662de..80eb87acf 100644 --- a/internal/api/client/status/statusunfave.go +++ b/internal/api/client/status/statusunfave.go @@ -26,7 +26,41 @@ import ( "github.com/superseriousbusiness/gotosocial/internal/oauth" ) -// StatusUnfavePOSTHandler is for undoing a fave on a status with a given ID +// StatusUnfavePOSTHandler swagger:operation POST /api/v1/statuses/{id}/unfavourite statusUnfave +// +// Unstar/unlike/unfavourite the given status. +// +// --- +// tags: +// - statuses +// +// produces: +// - application/json +// +// parameters: +// - name: id +// type: string +// description: Target status ID. +// in: path +// required: true +// +// security: +// - OAuth2 Bearer: +// - write:statuses +// +// responses: +// '200': +// description: "The unfaved status." +// schema: +// "$ref": "#/definitions/status" +// '400': +// description: bad request +// '401': +// description: unauthorized +// '403': +// description: forbidden +// '404': +// description: not found func (m *Module) StatusUnfavePOSTHandler(c *gin.Context) { l := m.log.WithFields(logrus.Fields{ "func": "StatusUnfavePOSTHandler", -- cgit v1.3