diff options
Diffstat (limited to 'internal/api/client')
38 files changed, 1056 insertions, 138 deletions
diff --git a/internal/api/client/account/accountcreate.go b/internal/api/client/account/accountcreate.go index e7b05fcc6..50e72655e 100644 --- a/internal/api/client/account/accountcreate.go +++ b/internal/api/client/account/accountcreate.go @@ -30,13 +30,13 @@ import ( "github.com/superseriousbusiness/gotosocial/internal/util" ) -// AccountCreatePOSTHandler handles create account requests, validates them, -// and puts them in the database if they're valid. -// -// swagger:operation POST /api/v1/accounts accountCreate +// AccountCreatePOSTHandler swagger:operation POST /api/v1/accounts accountCreate // // Create a new account using an application token. // +// 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: // - accounts @@ -45,17 +45,10 @@ import ( // - 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 diff --git a/internal/api/client/account/accountget.go b/internal/api/client/account/accountget.go index ff7c1a485..a7f9d8c70 100644 --- a/internal/api/client/account/accountget.go +++ b/internal/api/client/account/accountget.go @@ -25,9 +25,7 @@ import ( "github.com/superseriousbusiness/gotosocial/internal/oauth" ) -// AccountGETHandler returns info about the given account. -// -// swagger:operation GET /api/v1/accounts/{id} accountGet +// AccountGETHandler swagger:operation GET /api/v1/accounts/{id} accountGet // // Get information about an account with the given ID. // diff --git a/internal/api/client/account/accountupdate.go b/internal/api/client/account/accountupdate.go index 6d9a3f3f9..f55f45f59 100644 --- a/internal/api/client/account/accountupdate.go +++ b/internal/api/client/account/accountupdate.go @@ -26,10 +26,7 @@ import ( "github.com/superseriousbusiness/gotosocial/internal/oauth" ) -// AccountUpdateCredentialsPATCHHandler allows a user to modify their account/profile settings. -// It should be served as a PATCH at /api/v1/accounts/update_credentials -// -// swagger:operation PATCH /api/v1/accounts/update_credentials accountUpdate +// AccountUpdateCredentialsPATCHHandler swagger:operation PATCH /api/v1/accounts/update_credentials accountUpdate // // Update your account. // @@ -56,10 +53,12 @@ import ( // in: formData // description: The display name to use for the account. // type: string +// allowEmptyValue: true // - name: note // in: formData // description: Bio/description of this account. // type: string +// allowEmptyValue: true // - name: avatar // in: formData // description: Avatar of the user. @@ -72,15 +71,15 @@ import ( // in: formData // description: Require manual approval of follow requests. // type: boolean -// - name: source.privacy +// - name: source[privacy] // in: formData // description: Default post privacy for authored statuses. // type: string -// - name: source.sensitive +// - name: source[sensitive] // in: formData // description: Mark authored statuses as sensitive by default. // type: boolean -// - name: source.language +// - name: source[language] // in: formData // description: Default language to use for authored statuses (ISO 6391). // type: string diff --git a/internal/api/client/account/accountverify.go b/internal/api/client/account/accountverify.go index 0ff61362d..4c77f3fa6 100644 --- a/internal/api/client/account/accountverify.go +++ b/internal/api/client/account/accountverify.go @@ -25,11 +25,7 @@ import ( "github.com/superseriousbusiness/gotosocial/internal/oauth" ) -// 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. -// -// swagger:operation GET /api/v1/accounts/verify_credentials accountVerify +// AccountVerifyGETHandler swagger:operation GET /api/v1/accounts/verify_credentials accountVerify // // Verify a token by returning account details pertaining to it. // diff --git a/internal/api/client/account/block.go b/internal/api/client/account/block.go index ec2ba5b2c..0d9d6c51b 100644 --- a/internal/api/client/account/block.go +++ b/internal/api/client/account/block.go @@ -25,9 +25,7 @@ import ( "github.com/superseriousbusiness/gotosocial/internal/oauth" ) -// 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 +// AccountBlockPOSTHandler swagger:operation POST /api/v1/accounts/{id}/block accountBlock // // Block account with id. // diff --git a/internal/api/client/account/follow.go b/internal/api/client/account/follow.go index a0c5213fa..985a5f821 100644 --- a/internal/api/client/account/follow.go +++ b/internal/api/client/account/follow.go @@ -26,25 +26,43 @@ import ( "github.com/superseriousbusiness/gotosocial/internal/oauth" ) -// AccountFollowPOSTHandler is the endpoint for creating a new follow request to the target account -// -// swagger:operation POST /api/v1/accounts/{id}/follow accountFollow +// AccountFollowPOSTHandler swagger:operation POST /api/v1/accounts/{id}/follow accountFollow // // Follow account with id. // +// 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: // - accounts // -// produces: +// consumes: // - application/json +// - application/xml +// - application/x-www-form-urlencoded // // parameters: // - name: id -// type: string -// description: The id of the account to follow. -// in: path // required: true +// in: path +// description: ID of the account to follow. +// type: string +// - default: true +// description: Show reblogs from this account. +// in: formData +// name: reblogs +// type: boolean +// x-go-name: Reblogs +// - default: false +// description: Notify when this account posts. +// in: formData +// name: notify +// type: boolean +// x-go-name: Notify +// +// produces: +// - application/json // // security: // - OAuth2 Bearer: @@ -79,7 +97,7 @@ func (m *Module) AccountFollowPOSTHandler(c *gin.Context) { c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()}) return } - form.TargetAccountID = targetAcctID + form.ID = targetAcctID relationship, errWithCode := m.processor.AccountFollowCreate(authed, form) if errWithCode != nil { diff --git a/internal/api/client/account/followers.go b/internal/api/client/account/followers.go index 85bb65978..7e93544b8 100644 --- a/internal/api/client/account/followers.go +++ b/internal/api/client/account/followers.go @@ -25,9 +25,7 @@ import ( "github.com/superseriousbusiness/gotosocial/internal/oauth" ) -// AccountFollowersGETHandler serves the followers of the requested account, if they're visible to the requester. -// -// swagger:operation GET /api/v1/accounts/{id}/followers accountFollowers +// AccountFollowersGETHandler swagger:operation GET /api/v1/accounts/{id}/followers accountFollowers // // See followers of account with given id. // diff --git a/internal/api/client/account/following.go b/internal/api/client/account/following.go index e0ab2748b..e70265eb5 100644 --- a/internal/api/client/account/following.go +++ b/internal/api/client/account/following.go @@ -25,9 +25,7 @@ import ( "github.com/superseriousbusiness/gotosocial/internal/oauth" ) -// AccountFollowingGETHandler serves the following of the requested account, if they're visible to the requester. -// -// swagger:operation GET /api/v1/accounts/{id}/following accountFollowing +// AccountFollowingGETHandler swagger:operation GET /api/v1/accounts/{id}/following accountFollowing // // See accounts followed by given account id. // diff --git a/internal/api/client/account/relationships.go b/internal/api/client/account/relationships.go index b0404c3a1..9dbc8c4bb 100644 --- a/internal/api/client/account/relationships.go +++ b/internal/api/client/account/relationships.go @@ -8,9 +8,7 @@ import ( "github.com/superseriousbusiness/gotosocial/internal/oauth" ) -// AccountRelationshipsGETHandler serves the relationship of the requesting account with one or more requested account IDs. -// -// swagger:operation GET /api/v1/accounts/relationships accountRelationships +// AccountRelationshipsGETHandler swagger:operation GET /api/v1/accounts/relationships accountRelationships // // See your account's relationships with the given account IDs. // diff --git a/internal/api/client/account/statuses.go b/internal/api/client/account/statuses.go index 8e9faffcf..097ccc3cc 100644 --- a/internal/api/client/account/statuses.go +++ b/internal/api/client/account/statuses.go @@ -26,9 +26,7 @@ import ( "github.com/superseriousbusiness/gotosocial/internal/oauth" ) -// AccountStatusesGETHandler serves the statuses of the requested account, if they're visible to the requester. -// -// swagger:operation GET /api/v1/accounts/{id}/statuses accountStatuses +// AccountStatusesGETHandler swagger:operation GET /api/v1/accounts/{id}/statuses accountStatuses // // See statuses posted by the requested account. // @@ -86,7 +84,7 @@ import ( // responses: // '200': // name: statuses -// description: Array of statuses.. +// description: Array of statuses. // schema: // type: array // items: diff --git a/internal/api/client/account/unblock.go b/internal/api/client/account/unblock.go index 60b7c766d..d9a2f2881 100644 --- a/internal/api/client/account/unblock.go +++ b/internal/api/client/account/unblock.go @@ -25,9 +25,7 @@ import ( "github.com/superseriousbusiness/gotosocial/internal/oauth" ) -// 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 +// AccountUnblockPOSTHandler swagger:operation POST /api/v1/accounts/{id}/unblock accountUnblock // // Unblock account with ID. // diff --git a/internal/api/client/account/unfollow.go b/internal/api/client/account/unfollow.go index ba0ab8426..84a558c65 100644 --- a/internal/api/client/account/unfollow.go +++ b/internal/api/client/account/unfollow.go @@ -25,9 +25,7 @@ import ( "github.com/superseriousbusiness/gotosocial/internal/oauth" ) -// 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 +// AccountUnfollowPOSTHandler swagger:operation POST /api/v1/accounts/{id}/unfollow accountUnfollow // // Unfollow account with id. // diff --git a/internal/api/client/admin/domainblockcreate.go b/internal/api/client/admin/domainblockcreate.go index 8b9071c7c..d48c70408 100644 --- a/internal/api/client/admin/domainblockcreate.go +++ b/internal/api/client/admin/domainblockcreate.go @@ -12,13 +12,11 @@ import ( "github.com/superseriousbusiness/gotosocial/internal/oauth" ) -// DomainBlocksPOSTHandler deals with the creation of one or more domain blocks. -// -// swagger:operation PATCH /api/v1/admin/domain_blocks domainBlockCreate +// DomainBlocksPOSTHandler swagger:operation POST /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 +// 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. // @@ -46,38 +44,35 @@ import ( // in: formData // description: |- // JSON-formatted list of domain blocks to import. -// This is only used if 'import' is set to true. +// 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. +// 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. +// 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. +// 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. +// 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: @@ -86,9 +81,8 @@ import ( // 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. +// 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': diff --git a/internal/api/client/admin/domainblockdelete.go b/internal/api/client/admin/domainblockdelete.go index 8b773a5a9..9cd2fd711 100644 --- a/internal/api/client/admin/domainblockdelete.go +++ b/internal/api/client/admin/domainblockdelete.go @@ -8,9 +8,7 @@ import ( "github.com/superseriousbusiness/gotosocial/internal/oauth" ) -// DomainBlockDELETEHandler deals with the delete of an existing domain block. -// -// swagger:operation DELETE /api/v1/admin/domain_blocks/{id} domainBlockDelete +// DomainBlockDELETEHandler swagger:operation DELETE /api/v1/admin/domain_blocks/{id} domainBlockDelete // // Delete domain block with the given ID. // diff --git a/internal/api/client/admin/domainblockget.go b/internal/api/client/admin/domainblockget.go index 5fd48ba23..86923d705 100644 --- a/internal/api/client/admin/domainblockget.go +++ b/internal/api/client/admin/domainblockget.go @@ -9,9 +9,7 @@ import ( "github.com/superseriousbusiness/gotosocial/internal/oauth" ) -// DomainBlockGETHandler returns one existing domain block, identified by its id. -// -// swagger:operation GET /api/v1/admin/domain_blocks/{id} domainBlockGet +// DomainBlockGETHandler swagger:operation GET /api/v1/admin/domain_blocks/{id} domainBlockGet // // View domain block with the given ID. // diff --git a/internal/api/client/admin/domainblocksget.go b/internal/api/client/admin/domainblocksget.go index 70f1f5d08..77a287387 100644 --- a/internal/api/client/admin/domainblocksget.go +++ b/internal/api/client/admin/domainblocksget.go @@ -9,9 +9,7 @@ import ( "github.com/superseriousbusiness/gotosocial/internal/oauth" ) -// DomainBlocksGETHandler returns a list of all existing domain blocks. -// -// swagger:operation GET /api/v1/admin/domain_blocks domainBlocksGet +// DomainBlocksGETHandler swagger:operation GET /api/v1/admin/domain_blocks domainBlocksGet // // View all domain blocks currently in place. // diff --git a/internal/api/client/admin/emojicreate.go b/internal/api/client/admin/emojicreate.go index 94e6ecf7a..bfdf28249 100644 --- a/internal/api/client/admin/emojicreate.go +++ b/internal/api/client/admin/emojicreate.go @@ -31,9 +31,7 @@ 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 +// emojiCreateRequest swagger:operation POST /api/v1/admin/custom_emojis emojiCreate // // Upload and create a new instance emoji. // @@ -55,11 +53,12 @@ import ( // This must be unique on the instance. // type: string // pattern: \w{2,30} -// example: blobcat_uwu -// - name: domains +// required: true +// - name: image // in: formData // description: A png or gif image of the emoji. Animated pngs work too! // type: file +// required: true // // security: // - OAuth2 Bearer: diff --git a/internal/api/client/app/appcreate.go b/internal/api/client/app/appcreate.go index fd42482d4..31072f9c8 100644 --- a/internal/api/client/app/appcreate.go +++ b/internal/api/client/app/appcreate.go @@ -27,8 +27,41 @@ import ( "github.com/superseriousbusiness/gotosocial/internal/oauth" ) -// AppsPOSTHandler should be served at https://example.org/api/v1/apps -// It is equivalent to: https://docs.joinmastodon.org/methods/apps/ +// AppsPOSTHandler swagger:operation POST /api/v1/apps appCreate +// +// Register a new application on this instance. +// +// The registered application can be used to obtain an application token. +// This can then be used to register a new account, or (through user auth) obtain an access token. +// +// 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: +// - apps +// +// consumes: +// - application/json +// - application/xml +// - application/x-www-form-urlencoded +// +// produces: +// - application/json +// +// responses: +// '200': +// description: "The newly-created application." +// schema: +// "$ref": "#/definitions/application" +// '401': +// description: unauthorized +// '400': +// description: bad request +// '422': +// description: unprocessable +// '500': +// description: internal error func (m *Module) AppsPOSTHandler(c *gin.Context) { l := m.log.WithField("func", "AppsPOSTHandler") l.Trace("entering AppsPOSTHandler") diff --git a/internal/api/client/blocks/blocksget.go b/internal/api/client/blocks/blocksget.go index bf5f41e40..65c11ea1a 100644 --- a/internal/api/client/blocks/blocksget.go +++ b/internal/api/client/blocks/blocksget.go @@ -26,7 +26,63 @@ import ( "github.com/superseriousbusiness/gotosocial/internal/oauth" ) -// BlocksGETHandler handles GETting blocks. +// BlocksGETHandler swagger:operation GET /api/v1/blocks blocksGet +// +// Get an array of accounts that requesting account has blocked. +// +// The next and previous queries can be parsed from the returned Link header. +// Example: +// +// ``` +// <https://example.org/api/v1/blocks?limit=80&max_id=01FC0SKA48HNSVR6YKZCQGS2V8>; rel="next", <https://example.org/api/v1/blocks?limit=80&min_id=01FC0SKW5JK2Q4EVAV2B462YY0>; rel="prev" +// ```` +// +// --- +// tags: +// - blocks +// +// produces: +// - application/json +// +// parameters: +// - name: limit +// type: integer +// description: Number of blocks to return. +// default: 20 +// in: query +// - name: max_id +// type: string +// description: |- +// Return only blocks *OLDER* than the given max block ID. +// The block with the specified ID will not be included in the response. +// in: query +// - name: since_id +// type: string +// description: |- +// Return only blocks *NEWER* than the given since block ID. +// The block with the specified ID will not be included in the response. +// in: query +// +// security: +// - OAuth2 Bearer: +// - read:blocks +// +// responses: +// '200': +// headers: +// Link: +// type: string +// description: Links to the next and previous queries. +// schema: +// type: array +// items: +// "$ref": "#/definitions/account" +// '401': +// description: unauthorized +// '400': +// description: bad request +// '404': +// description: not found func (m *Module) BlocksGETHandler(c *gin.Context) { l := m.log.WithField("func", "PublicTimelineGETHandler") diff --git a/internal/api/client/instance/instanceget.go b/internal/api/client/instance/instanceget.go index 6ae419a83..0d53edadb 100644 --- a/internal/api/client/instance/instanceget.go +++ b/internal/api/client/instance/instanceget.go @@ -6,7 +6,28 @@ import ( "github.com/gin-gonic/gin" ) -// InstanceInformationGETHandler is for serving instance information at /api/v1/instance +// InstanceInformationGETHandler swagger:operation GET /api/v1/instance instanceGet +// +// View instance information. +// +// This is mostly provided for Mastodon application compatibility, since many apps that work with Mastodon use `/api/v1/instance` to inform their connection parameters. +// +// However, it can also be used by other instances for gathering instance information and representing instances in some UI or other. +// +// --- +// tags: +// - instance +// +// produces: +// - application/json +// +// responses: +// '200': +// description: "Instance information." +// schema: +// "$ref": "#/definitions/instance" +// '500': +// description: internal error func (m *Module) InstanceInformationGETHandler(c *gin.Context) { l := m.log.WithField("func", "InstanceInformationGETHandler") diff --git a/internal/api/client/instance/instancepatch.go b/internal/api/client/instance/instancepatch.go index 1080574c4..3620f6044 100644 --- a/internal/api/client/instance/instancepatch.go +++ b/internal/api/client/instance/instancepatch.go @@ -8,7 +8,81 @@ import ( "github.com/superseriousbusiness/gotosocial/internal/oauth" ) -// InstanceUpdatePATCHHandler allows an admin to update the instance information served at /api/v1/instance +// InstanceUpdatePATCHHandler swagger:operation PATCH /api/v1/instance instanceUpdate +// +// Update your instance information and/or upload a new avatar/header for the instance. +// +// This requires admin permissions on the instance. +// +// --- +// tags: +// - instance +// +// consumes: +// - multipart/form-data +// +// produces: +// - application/json +// +// parameters: +// - name: title +// in: formData +// description: Title to use for the instance. +// type: string +// maximum: 40 +// allowEmptyValue: true +// - name: contact_username +// in: formData +// description: |- +// Username of the contact account. +// This must be the username of an instance admin. +// type: string +// allowEmptyValue: true +// - name: contact_email +// in: formData +// description: Email address to use as the instance contact. +// type: string +// allowEmptyValue: true +// - name: short_description +// in: formData +// description: Short description of the instance. +// type: string +// maximum: 500 +// allowEmptyValue: true +// - name: description +// in: formData +// description: Longer description of the instance. +// type: string +// maximum: 5000 +// allowEmptyValue: true +// - name: terms +// in: formData +// description: Terms and conditions of the instance. +// type: string +// maximum: 5000 +// allowEmptyValue: true +// - name: avatar +// in: formData +// description: Avatar of the instance. +// type: file +// - name: header +// in: formData +// description: Header of the instance. +// type: file +// +// security: +// - OAuth2 Bearer: +// - admin +// +// responses: +// '200': +// description: "The newly updated instance." +// schema: +// "$ref": "#/definitions/instance" +// '401': +// description: unauthorized +// '400': +// description: bad request func (m *Module) InstanceUpdatePATCHHandler(c *gin.Context) { l := m.log.WithField("func", "InstanceUpdatePATCHHandler") authed, err := oauth.Authed(c, true, true, true, true) diff --git a/internal/api/client/media/mediacreate.go b/internal/api/client/media/mediacreate.go index 9f4702b6b..f41d4568f 100644 --- a/internal/api/client/media/mediacreate.go +++ b/internal/api/client/media/mediacreate.go @@ -29,7 +29,58 @@ import ( "github.com/superseriousbusiness/gotosocial/internal/oauth" ) -// MediaCreatePOSTHandler handles requests to create/upload media attachments +// MediaCreatePOSTHandler swagger:operation POST /api/v1/media mediaCreate +// +// Upload a new media attachment. +// +// --- +// tags: +// - media +// +// consumes: +// - multipart/form-data +// +// produces: +// - application/json +// +// parameters: +// - name: description +// in: formData +// description: |- +// Image or media description to use as alt-text on the attachment. +// This is very useful for users of screenreaders. +// May or may not be required, depending on your instance settings. +// type: string +// - name: focus +// in: formData +// description: |- +// Focus of the media file. +// If present, it should be in the form of two comma-separated floats between -1 and 1. +// For example: `-0.5,0.25`. +// type: string +// - name: file +// in: formData +// description: The media attachment to upload. +// type: file +// required: true +// +// security: +// - OAuth2 Bearer: +// - write:media +// +// responses: +// '200': +// description: The newly-created media attachment. +// schema: +// "$ref": "#/definitions/attachment" +// '400': +// description: bad request +// '401': +// description: unauthorized +// '403': +// description: forbidden +// '422': +// description: unprocessable func (m *Module) MediaCreatePOSTHandler(c *gin.Context) { l := m.log.WithField("func", "statusCreatePOSTHandler") authed, err := oauth.Authed(c, true, true, true, true) // posting new media is serious business so we want *everything* diff --git a/internal/api/client/media/mediaget.go b/internal/api/client/media/mediaget.go index 7acb475ce..17c5a090b 100644 --- a/internal/api/client/media/mediaget.go +++ b/internal/api/client/media/mediaget.go @@ -1,12 +1,3 @@ -package media - -import ( - "net/http" - - "github.com/gin-gonic/gin" - "github.com/superseriousbusiness/gotosocial/internal/oauth" -) - /* GoToSocial Copyright (C) 2021 GoToSocial Authors admin@gotosocial.org @@ -25,7 +16,50 @@ import ( along with this program. If not, see <http://www.gnu.org/licenses/>. */ -// MediaGETHandler allows the owner of an attachment to get information about that attachment before it's used in a status. +package media + +import ( + "net/http" + + "github.com/gin-gonic/gin" + "github.com/superseriousbusiness/gotosocial/internal/oauth" +) + +// MediaGETHandler swagger:operation GET /api/v1/media/{id} mediaGet +// +// Get a media attachment that you own. +// +// --- +// tags: +// - media +// +// produces: +// - application/json +// +// parameters: +// - name: id +// description: id of the attachment +// type: string +// in: path +// required: true +// +// security: +// - OAuth2 Bearer: +// - read:media +// +// responses: +// '200': +// description: The requested media attachment. +// schema: +// "$ref": "#/definitions/attachment" +// '400': +// description: bad request +// '401': +// description: unauthorized +// '403': +// description: forbidden +// '422': +// description: unprocessable func (m *Module) MediaGETHandler(c *gin.Context) { l := m.log.WithField("func", "MediaGETHandler") authed, err := oauth.Authed(c, true, true, true, true) diff --git a/internal/api/client/media/mediaupdate.go b/internal/api/client/media/mediaupdate.go index 29ab04947..0ceb01f82 100644 --- a/internal/api/client/media/mediaupdate.go +++ b/internal/api/client/media/mediaupdate.go @@ -1,16 +1,3 @@ -package media - -import ( - "errors" - "fmt" - "net/http" - - "github.com/gin-gonic/gin" - "github.com/superseriousbusiness/gotosocial/internal/api/model" - "github.com/superseriousbusiness/gotosocial/internal/config" - "github.com/superseriousbusiness/gotosocial/internal/oauth" -) - /* GoToSocial Copyright (C) 2021 GoToSocial Authors admin@gotosocial.org @@ -29,7 +16,80 @@ import ( along with this program. If not, see <http://www.gnu.org/licenses/>. */ -// MediaPUTHandler allows the owner of an attachment to update information about that attachment before it's used in a status. +package media + +import ( + "errors" + "fmt" + "net/http" + + "github.com/gin-gonic/gin" + "github.com/superseriousbusiness/gotosocial/internal/api/model" + "github.com/superseriousbusiness/gotosocial/internal/config" + "github.com/superseriousbusiness/gotosocial/internal/oauth" +) + +// MediaPUTHandler swagger:operation PUT /api/v1/media/{id} mediaUpdate +// +// Update a media attachment. +// +// You must own the media attachment, and the attachment must not yet be attached to a 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: +// - media +// +// consumes: +// - application/json +// - application/xml +// - application/x-www-form-urlencoded +// +// produces: +// - application/json +// +// parameters: +// - name: id +// description: id of the attachment to update +// type: string +// in: path +// required: true +// - name: description +// in: formData +// description: |- +// Image or media description to use as alt-text on the attachment. +// This is very useful for users of screenreaders. +// May or may not be required, depending on your instance settings. +// type: string +// allowEmptyValue: true +// - name: focus +// in: formData +// description: |- +// Focus of the media file. +// If present, it should be in the form of two comma-separated floats between -1 and 1. +// For example: `-0.5,0.25`. +// type: string +// allowEmptyValue: true +// +// security: +// - OAuth2 Bearer: +// - write:media +// +// responses: +// '200': +// description: The newly-updated media attachment. +// schema: +// "$ref": "#/definitions/attachment" +// '400': +// description: bad request +// '401': +// description: unauthorized +// '403': +// description: forbidden +// '422': +// description: unprocessable func (m *Module) MediaPUTHandler(c *gin.Context) { l := m.log.WithField("func", "MediaGETHandler") authed, err := oauth.Authed(c, true, true, true, true) diff --git a/internal/api/client/search/searchget.go b/internal/api/client/search/searchget.go index 1e2694673..faa227719 100644 --- a/internal/api/client/search/searchget.go +++ b/internal/api/client/search/searchget.go @@ -29,8 +29,32 @@ import ( "github.com/superseriousbusiness/gotosocial/internal/oauth" ) -// SearchGETHandler handles searches for local and remote accounts, statuses, and hashtags. -// It corresponds to the mastodon endpoint described here: https://docs.joinmastodon.org/methods/search/ +// SearchGETHandler swagger:operation GET /api/v1/search searchGet +// +// Search for statuses, accounts, or hashtags, on this instance or elsewhere. +// +// If statuses are in the result, they will be returned in descending chronological order (newest first), with sequential IDs (bigger = newer). +// +// --- +// tags: +// - search +// +// security: +// - OAuth2 Bearer: +// - read:search +// +// responses: +// '200': +// name: search results +// description: Results of the search. +// schema: +// type: array +// items: +// "$ref": "#/definitions/searchResult" +// '401': +// description: unauthorized +// '400': +// description: bad request func (m *Module) SearchGETHandler(c *gin.Context) { l := m.log.WithFields(logrus.Fields{ "func": "SearchGETHandler", 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/statusboostedby.go index debcc1b22..260e21642 100644 --- a/internal/api/client/status/statusboosted_by.go +++ b/internal/api/client/status/statusboostedby.go @@ -26,7 +26,42 @@ import ( "github.com/superseriousbusiness/gotosocial/internal/oauth" ) -// StatusBoostedByGETHandler is for serving a list of accounts that have boosted/reblogged a given status +// 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", 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", diff --git a/internal/api/client/streaming/stream.go b/internal/api/client/streaming/stream.go index 20a12fefe..626f1ff41 100644 --- a/internal/api/client/streaming/stream.go +++ b/internal/api/client/streaming/stream.go @@ -9,7 +9,103 @@ import ( "github.com/gorilla/websocket" ) -// StreamGETHandler handles the creation of a new websocket streaming request. +// StreamGETHandler swagger:operation GET /api/v1/streaming streamGet +// +// Initiate a websocket connection for live streaming of statuses and notifications. +// +// The scheme used should *always* be `wss`. The streaming basepath can be viewed at `/api/v1/instance`. +// +// On a successful connection, a code `101` will be returned, which indicates that the connection is being upgraded to a secure websocket connection. +// +// As long as the connection is open, various message types will be streamed into it. +// +// GoToSocial will ping the connection every 30 seconds to check whether the client is still receiving. +// +// If the ping fails, or something else goes wrong during transmission, then the connection will be dropped, and the client will be expected to start it again. +// +// --- +// tags: +// - streaming +// +// produces: +// - application/json +// +// schemes: +// - wss +// +// parameters: +// - name: access_token +// type: string +// description: Access token for the requesting account. +// in: query +// required: true +// - name: stream +// type: string +// description: |- +// Type of stream to request. +// +// Options are: +// +// `user`: receive updates for the account's home timeline. +// `public`: receive updates for the public timeline. +// `public:local`: receive updates for the local timeline. +// `hashtag`: receive updates for a given hashtag. +// `hashtag:local`: receive local updates for a given hashtag. +// `list`: receive updates for a certain list of accounts. +// `direct`: receive updates for direct messages. +// in: query +// required: true +// security: +// - OAuth2 Bearer: +// - read:streaming +// +// responses: +// '101': +// schema: +// type: object +// properties: +// stream: +// type: array +// items: +// type: string +// enum: +// - user +// - public +// - public:local +// - hashtag +// - hashtag:local +// - list +// - direct +// event: +// description: |- +// The type of event being received. +// +// `update`: a new status has been received. +// `notification`: a new notification has been received. +// `delete`: a status has been deleted. +// `filters_changed`: not implemented. +// type: string +// enum: +// - update +// - notification +// - delete +// - filters_changed +// payload: +// description: |- +// The payload of the streamed message. +// Different depending on the `event` type. +// +// If present, it should be parsed as a string. +// +// If `event` = `update`, then the payload will be a JSON string of a status. +// If `event` = `notification`, then the payload will be a JSON string of a notification. +// If `event` = `delete`, then the payload will be a status ID. +// type: string +// example: "{\"id\":\"01FC3TZ5CFG6H65GCKCJRKA669\",\"created_at\":\"2021-08-02T16:25:52Z\",\"sensitive\":false,\"spoiler_text\":\"\",\"visibility\":\"public\",\"language\":\"en\",\"uri\":\"https://gts.superseriousbusiness.org/users/dumpsterqueer/statuses/01FC3TZ5CFG6H65GCKCJRKA669\",\"url\":\"https://gts.superseriousbusiness.org/@dumpsterqueer/statuses/01FC3TZ5CFG6H65GCKCJRKA669\",\"replies_count\":0,\"reblogs_count\":0,\"favourites_count\":0,\"favourited\":false,\"reblogged\":false,\"muted\":false,\"bookmarked\":fals…//gts.superseriousbusiness.org/fileserver/01JNN207W98SGG3CBJ76R5MVDN/header/original/019036W043D8FXPJKSKCX7G965.png\",\"header_static\":\"https://gts.superseriousbusiness.org/fileserver/01JNN207W98SGG3CBJ76R5MVDN/header/small/019036W043D8FXPJKSKCX7G965.png\",\"followers_count\":33,\"following_count\":28,\"statuses_count\":126,\"last_status_at\":\"2021-08-02T16:25:52Z\",\"emojis\":[],\"fields\":[]},\"media_attachments\":[],\"mentions\":[],\"tags\":[],\"emojis\":[],\"card\":null,\"poll\":null,\"text\":\"a\"}" +// '401': +// description: unauthorized +// '400': +// description: bad request func (m *Module) StreamGETHandler(c *gin.Context) { l := m.log.WithField("func", "StreamGETHandler") diff --git a/internal/api/client/timeline/home.go b/internal/api/client/timeline/home.go index cb72895f9..a6e64f384 100644 --- a/internal/api/client/timeline/home.go +++ b/internal/api/client/timeline/home.go @@ -26,15 +26,81 @@ import ( "github.com/superseriousbusiness/gotosocial/internal/oauth" ) -// HomeTimelineGETHandler serves status from the HOME timeline. +// HomeTimelineGETHandler swagger:operation GET /api/v1/timelines/home homeTimeline // -// Several different filters might be passed into this function in the query: +// See statuses/posts by accounts you follow. // -// max_id -- the maximum ID of the status to show -// since_id -- Return results newer than id -// min_id -- Return results immediately newer than id -// limit -- show only limit number of statuses -// local -- Return only local statuses? +// The statuses will be returned in descending chronological order (newest first), with sequential IDs (bigger = newer). +// +// The returned Link header can be used to generate the previous and next queries when scrolling up or down a timeline. +// +// Example: +// +// ``` +// <https://example.org/api/v1/timelines/home?limit=20&max_id=01FC3GSQ8A3MMJ43BPZSGEG29M>; rel="next", <https://example.org/api/v1/timelines/home?limit=20&min_id=01FC3KJW2GYXSDDRA6RWNDM46M>; rel="prev" +// ```` +// +// --- +// tags: +// - timelines +// +// produces: +// - application/json +// +// parameters: +// - 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: since_id +// type: string +// description: |- +// Return only statuses *NEWER* than the given since status ID. +// The status with the specified ID will not be included in the response. +// in: query +// - name: min_id +// type: string +// description: |- +// Return only statuses *NEWER* than the given since status ID. +// The status with the specified ID will not be included in the response. +// in: query +// required: false +// - name: limit +// type: integer +// description: Number of statuses to return. +// default: 20 +// in: query +// required: false +// - name: local +// type: boolean +// description: Show only statuses posted by local accounts. +// default: false +// in: query +// required: false +// +// security: +// - OAuth2 Bearer: +// - read:statuses +// +// responses: +// '200': +// name: statuses +// description: Array of statuses. +// schema: +// type: array +// items: +// "$ref": "#/definitions/status" +// headers: +// Link: +// type: string +// description: Links to the next and previous queries. +// '401': +// description: unauthorized +// '400': +// description: bad request func (m *Module) HomeTimelineGETHandler(c *gin.Context) { l := m.log.WithField("func", "HomeTimelineGETHandler") diff --git a/internal/api/client/timeline/public.go b/internal/api/client/timeline/public.go index 6898d781b..178fcd7f1 100644 --- a/internal/api/client/timeline/public.go +++ b/internal/api/client/timeline/public.go @@ -26,9 +26,81 @@ import ( "github.com/superseriousbusiness/gotosocial/internal/oauth" ) -// PublicTimelineGETHandler handles PUBLIC timeline requests. -// This includes requests to local, which are actually just public -// requests with a filter. +// PublicTimelineGETHandler swagger:operation GET /api/v1/timelines/public publicTimeline +// +// See public statuses/posts that your instance is aware of. +// +// The statuses will be returned in descending chronological order (newest first), with sequential IDs (bigger = newer). +// +// The returned Link header can be used to generate the previous and next queries when scrolling up or down a timeline. +// +// Example: +// +// ``` +// <https://example.org/api/v1/timelines/public?limit=20&max_id=01FC3GSQ8A3MMJ43BPZSGEG29M>; rel="next", <https://example.org/api/v1/timelines/public?limit=20&min_id=01FC3KJW2GYXSDDRA6RWNDM46M>; rel="prev" +// ```` +// +// --- +// tags: +// - timelines +// +// produces: +// - application/json +// +// parameters: +// - 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: since_id +// type: string +// description: |- +// Return only statuses *NEWER* than the given since status ID. +// The status with the specified ID will not be included in the response. +// in: query +// - name: min_id +// type: string +// description: |- +// Return only statuses *NEWER* than the given since status ID. +// The status with the specified ID will not be included in the response. +// in: query +// required: false +// - name: limit +// type: integer +// description: Number of statuses to return. +// default: 20 +// in: query +// required: false +// - name: local +// type: boolean +// description: Show only statuses posted by local accounts. +// default: false +// in: query +// required: false +// +// security: +// - OAuth2 Bearer: +// - read:statuses +// +// responses: +// '200': +// name: statuses +// description: Array of statuses. +// schema: +// type: array +// items: +// "$ref": "#/definitions/status" +// headers: +// Link: +// type: string +// description: Links to the next and previous queries. +// '401': +// description: unauthorized +// '400': +// description: bad request func (m *Module) PublicTimelineGETHandler(c *gin.Context) { l := m.log.WithField("func", "PublicTimelineGETHandler") |