* start experimenting with swagger documentation

* further adventures in swagger

* do a few more api paths

* account paths documented

* go fmt

* fix up some models

* bit o lintin'
This commit is contained in:
Tobi Smethurst 2021-07-31 17:49:59 +02:00 committed by GitHub
parent eb13faf54f
commit 58dddd86e0
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
37 changed files with 2355 additions and 169 deletions

View file

@ -16,6 +16,30 @@
along with this program. If not, see <http://www.gnu.org/licenses/>.
*/
// Package classification awesome.
//
// Documentation of our awesome AaaaaaaaaaPI.
//
// Schemes: http
// BasePath: /
// Version: 1.0.0
// Host: some-url.com
//
// Consumes:
// - application/json
//
// Produces:
// - application/json
//
// Security:
// - basic
//
// SecurityDefinitions:
// basic:
// type: basic
//
// swagger:meta
package main
import (
@ -23,6 +47,7 @@ import (
"github.com/sirupsen/logrus"
_ "github.com/superseriousbusiness/gotosocial/docs"
"github.com/urfave/cli/v2"
)
@ -32,6 +57,7 @@ var Version string
// Commit is the git commit of GtS being used
var Commit string
//go:generate swagger generate spec
func main() {
var v string
if Commit == "" {

9
docs/api/swagger.md Normal file
View file

@ -0,0 +1,9 @@
# API Documentation
GoToSocial uses [go-swagger](https://github.com/go-swagger/go-swagger) to generate a V2 [OpenAPI specification](https://swagger.io/specification/v2/) document from code annotations.
The resulting API documentation is rendered below, for quick reference.
If you'd like to do more with the spec, you can also view the [swagger.yaml](/api/swagger/swagger.yaml) directly, and then paste it into something like the [Swagger Editor](https://editor.swagger.io/) in order to autogenerate GoToSocial API clients in different languages, convert the doc to JSON or OpenAPI v3 specification, etc. See [here](https://swagger.io/tools/open-source/getting-started/) for more.
!!swagger swagger.yaml!!

1476
docs/api/swagger.yaml Normal file

File diff suppressed because it is too large Load diff

File diff suppressed because one or more lines are too long

File diff suppressed because one or more lines are too long

File diff suppressed because one or more lines are too long

File diff suppressed because one or more lines are too long

52
docs/swagger.go Normal file
View file

@ -0,0 +1,52 @@
/*
GoToSocial
Copyright (C) 2021 GoToSocial Authors admin@gotosocial.org
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU Affero General Public License for more details.
You should have received a copy of the GNU Affero General Public License
along with this program. If not, see <http://www.gnu.org/licenses/>.
*/
// Package docs GoToSocial
//
// GoToSocial Swagger documentation.
//
// Schemes: https, http
// BasePath: /
// Version: REPLACE_ME
// Host: example.org
// License: AGPL3 https://www.gnu.org/licenses/agpl-3.0.en.html
// Contact: GoToSocial Authors <admin@gotosocial.org>
// SecurityDefinitions:
// OAuth2 Bearer:
// type: oauth2
// flow: accessCode
// authorizationUrl: https://example.org/oauth/authorize
// tokenUrl: https://example.org/oauth/token
// scopes:
// read: grants read access to everything
// read:accounts: grants read access to accounts
// write: grants write access to everything
// write:accounts: grants write access to accounts
// write:blocks: grants write access to blocks
// write:follows: grants write access to follows
// admin: grants admin access to everything
// admin:accounts: grants admin access to accounts
// OAuth2 Application:
// type: oauth2
// flow: application
// tokenUrl: https://example.org/oauth/token
// scopes:
// write:accounts: grants write access to accounts
//
// swagger:meta
package docs

7
generateswagger.sh Executable file
View file

@ -0,0 +1,7 @@
#!/bin/bash
SWAGGER_FILE="docs/api/swagger.yaml"
GTS_VERSION="$(cat version)"
swagger generate spec -o "${SWAGGER_FILE}" --scan-models
sed -i "s/REPLACE_ME/${GTS_VERSION}/" "${SWAGGER_FILE}"

View file

@ -32,13 +32,53 @@ import (
// AccountCreatePOSTHandler handles create account requests, validates them,
// and puts them in the database if they're valid.
// It should be served as a POST at /api/v1/accounts
//
// swagger:operation POST /api/v1/accounts accountCreate
//
// Create a new account using an application token.
//
// ---
// tags:
// - accounts
//
// consumes:
// - application/json
// - application/xml
// - application/x-www-form-urlencoded
// - multipart/form-data
//
// produces:
// - application/json
//
// parameters:
// - name: Account Create Request
// in: body
// schema:
// "$ref": "#/definitions/accountCreateRequest"
//
// security:
// - OAuth2 Application:
// - write:accounts
//
// responses:
// '200':
// description: "An OAuth2 access token for the newly-created account."
// schema:
// "$ref": "#/definitions/oauthToken"
// '401':
// description: unauthorized
// '400':
// description: bad request
// '404':
// description: not found
// '500':
// description: internal error
func (m *Module) AccountCreatePOSTHandler(c *gin.Context) {
l := m.log.WithField("func", "accountCreatePOSTHandler")
authed, err := oauth.Authed(c, true, true, false, false)
if err != nil {
l.Debugf("couldn't auth: %s", err)
c.JSON(http.StatusForbidden, gin.H{"error": err.Error()})
c.JSON(http.StatusUnauthorized, gin.H{"error": err.Error()})
return
}

View file

@ -25,12 +25,42 @@ import (
"github.com/superseriousbusiness/gotosocial/internal/oauth"
)
// AccountGETHandler serves the account information held by the server in response to a GET
// request. It should be served as a GET at /api/v1/accounts/:id.
// AccountGETHandler returns info about the given account.
//
// See: https://docs.joinmastodon.org/methods/accounts/
// swagger:operation GET /api/v1/accounts/{id} accountGet
//
// Get information about an account with the given ID.
//
// ---
// tags:
// - accounts
//
// produces:
// - application/json
//
// parameters:
// - name: id
// type: string
// description: The id of the requested account.
// in: path
// required: true
//
// security:
// - OAuth2 Bearer:
// - read:accounts
//
// responses:
// '200':
// schema:
// "$ref": "#/definitions/account"
// '401':
// description: unauthorized
// '400':
// description: bad request
// '404':
// description: not found
func (m *Module) AccountGETHandler(c *gin.Context) {
authed, err := oauth.Authed(c, false, false, false, false)
authed, err := oauth.Authed(c, true, true, true, true)
if err != nil {
c.JSON(http.StatusUnauthorized, gin.H{"error": "unauthorized"})
return

View file

@ -29,14 +29,78 @@ import (
// AccountUpdateCredentialsPATCHHandler allows a user to modify their account/profile settings.
// It should be served as a PATCH at /api/v1/accounts/update_credentials
//
// TODO: this can be optimized massively by building up a picture of what we want the new account
// details to be, and then inserting it all in the database at once. As it is, we do queries one-by-one
// which is not gonna make the database very happy when lots of requests are going through.
// This way it would also be safer because the update won't happen until *all* the fields are validated.
// Otherwise we risk doing a partial update and that's gonna cause probllleeemmmsss.
// swagger:operation PATCH /api/v1/accounts/update_credentials accountUpdate
//
// Update your account.
//
// ---
// tags:
// - accounts
//
// consumes:
// - multipart/form-data
//
// produces:
// - application/json
//
// parameters:
// - name: discoverable
// in: formData
// description: Account should be made discoverable and shown in the profile directory (if enabled).
// type: boolean
// - name: bot
// in: formData
// description: Account is flagged as a bot.
// type: boolean
// - name: display_name
// in: formData
// description: The display name to use for the account.
// type: string
// - name: note
// in: formData
// description: Bio/description of this account.
// type: string
// - name: avatar
// in: formData
// description: Avatar of the user.
// type: file
// - name: header
// in: formData
// description: Header of the user.
// type: file
// - name: locked
// in: formData
// description: Require manual approval of follow requests.
// type: boolean
// - name: source.privacy
// in: formData
// description: Default post privacy for authored statuses.
// type: string
// - name: source.sensitive
// in: formData
// description: Mark authored statuses as sensitive by default.
// type: boolean
// - name: source.language
// in: formData
// description: Default language to use for authored statuses (ISO 6391).
// type: string
//
// security:
// - OAuth2 Bearer:
// - write:accounts
//
// responses:
// '200':
// description: "The newly updated account."
// schema:
// "$ref": "#/definitions/account"
// '401':
// description: unauthorized
// '400':
// description: bad request
func (m *Module) AccountUpdateCredentialsPATCHHandler(c *gin.Context) {
l := m.log.WithField("func", "accountUpdateCredentialsPATCHHandler")
authed, err := oauth.Authed(c, true, false, false, true)
authed, err := oauth.Authed(c, true, true, true, true)
if err != nil {
l.Debugf("couldn't auth: %s", err)
c.JSON(http.StatusForbidden, gin.H{"error": err.Error()})

View file

@ -27,7 +27,33 @@ import (
// AccountVerifyGETHandler serves a user's account details to them IF they reached this
// handler while in possession of a valid token, according to the oauth middleware.
// It should be served as a GET at /api/v1/accounts/verify_credentials
// It should be served as a GET at /api/v1/accounts/verify_credentials.
//
// swagger:operation GET /api/v1/accounts/verify_credentials accountVerify
//
// Verify a token by returning account details pertaining to it.
//
// ---
// tags:
// - accounts
//
// produces:
// - application/json
//
// security:
// - OAuth2 Bearer:
// - read:accounts
//
// responses:
// '200':
// schema:
// "$ref": "#/definitions/account"
// '401':
// description: unauthorized
// '400':
// description: bad request
// '404':
// description: not found
func (m *Module) AccountVerifyGETHandler(c *gin.Context) {
l := m.log.WithField("func", "accountVerifyGETHandler")
authed, err := oauth.Authed(c, true, false, false, true)

View file

@ -26,6 +26,41 @@ import (
)
// AccountBlockPOSTHandler handles the creation of a block from the authed account targeting the given account ID.
//
// swagger:operation POST /api/v1/accounts/{id}/block accountBlock
//
// Block account with id.
//
// ---
// tags:
// - accounts
//
// produces:
// - application/json
//
// parameters:
// - name: id
// type: string
// description: The id of the account to block.
// in: path
// required: true
//
// security:
// - OAuth2 Bearer:
// - write:blocks
//
// responses:
// '200':
// name: account relationship
// description: Your relationship to this account.
// schema:
// "$ref": "#/definitions/accountRelationship"
// '401':
// description: unauthorized
// '400':
// description: bad request
// '404':
// description: not found
func (m *Module) AccountBlockPOSTHandler(c *gin.Context) {
authed, err := oauth.Authed(c, true, true, true, true)
if err != nil {

View file

@ -27,6 +27,41 @@ import (
)
// AccountFollowPOSTHandler is the endpoint for creating a new follow request to the target account
//
// swagger:operation POST /api/v1/accounts/{id}/follow accountFollow
//
// Follow account with id.
//
// ---
// tags:
// - accounts
//
// produces:
// - application/json
//
// parameters:
// - name: id
// type: string
// description: The id of the account to follow.
// in: path
// required: true
//
// security:
// - OAuth2 Bearer:
// - write:follows
//
// responses:
// '200':
// name: account relationship
// description: Your relationship to this account.
// schema:
// "$ref": "#/definitions/accountRelationship"
// '401':
// description: unauthorized
// '400':
// description: bad request
// '404':
// description: not found
func (m *Module) AccountFollowPOSTHandler(c *gin.Context) {
authed, err := oauth.Authed(c, true, true, true, true)
if err != nil {

View file

@ -26,6 +26,43 @@ import (
)
// AccountFollowersGETHandler serves the followers of the requested account, if they're visible to the requester.
//
// swagger:operation GET /api/v1/accounts/{id}/followers accountFollowers
//
// See followers of account with given id.
//
// ---
// tags:
// - accounts
//
// produces:
// - application/json
//
// parameters:
// - name: id
// type: string
// description: Account ID.
// in: path
// required: true
//
// security:
// - OAuth2 Bearer:
// - read:accounts
//
// responses:
// '200':
// name: accounts
// description: Array of accounts that follow this account.
// schema:
// type: array
// items:
// "$ref": "#/definitions/account"
// '401':
// description: unauthorized
// '400':
// description: bad request
// '404':
// description: not found
func (m *Module) AccountFollowersGETHandler(c *gin.Context) {
authed, err := oauth.Authed(c, true, true, true, true)
if err != nil {

View file

@ -26,6 +26,43 @@ import (
)
// AccountFollowingGETHandler serves the following of the requested account, if they're visible to the requester.
//
// swagger:operation GET /api/v1/accounts/{id}/following accountFollowing
//
// See accounts followed by given account id.
//
// ---
// tags:
// - accounts
//
// produces:
// - application/json
//
// parameters:
// - name: id
// type: string
// description: Account ID.
// in: path
// required: true
//
// security:
// - OAuth2 Bearer:
// - read:accounts
//
// responses:
// '200':
// name: accounts
// description: Array of accounts that are followed by this account.
// schema:
// type: array
// items:
// "$ref": "#/definitions/account"
// '401':
// description: unauthorized
// '400':
// description: bad request
// '404':
// description: not found
func (m *Module) AccountFollowingGETHandler(c *gin.Context) {
authed, err := oauth.Authed(c, true, true, true, true)
if err != nil {

View file

@ -9,6 +9,45 @@ import (
)
// AccountRelationshipsGETHandler serves the relationship of the requesting account with one or more requested account IDs.
//
// swagger:operation GET /api/v1/accounts/relationships accountRelationships
//
// See your account's relationships with the given account IDs.
//
// ---
// tags:
// - accounts
//
// produces:
// - application/json
//
// parameters:
// - name: id
// type: array
// items:
// type: string
// description: Account IDs.
// in: query
// required: true
//
// security:
// - OAuth2 Bearer:
// - read:accounts
//
// responses:
// '200':
// name: account relationships
// description: Array of account relationships.
// schema:
// type: array
// items:
// "$ref": "#/definitions/accountRelationship"
// '401':
// description: unauthorized
// '400':
// description: bad request
// '404':
// description: not found
func (m *Module) AccountRelationshipsGETHandler(c *gin.Context) {
l := m.log.WithField("func", "AccountRelationshipsGETHandler")

View file

@ -28,13 +28,75 @@ import (
// AccountStatusesGETHandler serves the statuses of the requested account, if they're visible to the requester.
//
// Several different filters might be passed into this function in the query:
// swagger:operation GET /api/v1/accounts/{id}/statuses accountStatuses
//
// limit -- show only limit number of statuses
// exclude_replies -- exclude statuses that are a reply to another status
// max_id -- the maximum ID of the status to show
// pinned -- show only pinned statuses
// media_only -- show only statuses that have media attachments
// See statuses posted by the requested account.
//
// The statuses will be returned in descending chronological order (newest first), with sequential IDs (bigger = newer).
//
// ---
// tags:
// - accounts
//
// produces:
// - application/json
//
// parameters:
// - name: id
// type: string
// description: Account ID.
// in: path
// required: true
// - name: limit
// type: integer
// description: Number of statuses to return.
// default: 30
// in: query
// required: false
// - name: exclude_replies
// type: boolean
// description: Exclude statuses that are a reply to another status.
// default: false
// in: query
// required: false
// - name: max_id
// type: string
// description: |-
// Return only statuses *OLDER* than the given max status ID.
// The status with the specified ID will not be included in the response.
// in: query
// required: false
// - name: pinned_only
// type: boolean
// description: Show only pinned statuses. In other words,e xclude statuses that are not pinned to the given account ID.
// default: false
// in: query
// required: false
// - name: media_only
// type: boolean
// description: Show only statuses with media attachments.
// default: false
// in: query
// required: false
//
// security:
// - OAuth2 Bearer:
// - read:accounts
//
// responses:
// '200':
// name: statuses
// description: Array of statuses..
// schema:
// type: array
// items:
// "$ref": "#/definitions/status"
// '401':
// description: unauthorized
// '400':
// description: bad request
// '404':
// description: not found
func (m *Module) AccountStatusesGETHandler(c *gin.Context) {
l := m.log.WithField("func", "AccountStatusesGETHandler")

View file

@ -26,6 +26,41 @@ import (
)
// AccountUnblockPOSTHandler handles the removal of a block from the authed account targeting the given account ID.
//
// swagger:operation POST /api/v1/accounts/{id}/unblock accountUnblock
//
// Unblock account with ID.
//
// ---
// tags:
// - accounts
//
// produces:
// - application/json
//
// parameters:
// - name: id
// type: string
// description: The id of the account to unblock.
// in: path
// required: true
//
// security:
// - OAuth2 Bearer:
// - write:blocks
//
// responses:
// '200':
// name: account relationship
// description: Your relationship to this account.
// schema:
// "$ref": "#/definitions/accountRelationship"
// '401':
// description: unauthorized
// '400':
// description: bad request
// '404':
// description: not found
func (m *Module) AccountUnblockPOSTHandler(c *gin.Context) {
authed, err := oauth.Authed(c, true, true, true, true)
if err != nil {

View file

@ -26,6 +26,41 @@ import (
)
// AccountUnfollowPOSTHandler is the endpoint for removing a follow and/or follow request to the target account
//
// swagger:operation POST /api/v1/accounts/{id}/unfollow accountUnfollow
//
// Unfollow account with id.
//
// ---
// tags:
// - accounts
//
// produces:
// - application/json
//
// parameters:
// - name: id
// type: string
// description: The id of the account to unfollow.
// in: path
// required: true
//
// security:
// - OAuth2 Bearer:
// - write:follows
//
// responses:
// '200':
// name: account relationship
// description: Your relationship to this account.
// schema:
// "$ref": "#/definitions/accountRelationship"
// '401':
// description: unauthorized
// '400':
// description: bad request
// '404':
// description: not found
func (m *Module) AccountUnfollowPOSTHandler(c *gin.Context) {
l := m.log.WithField("func", "AccountUnfollowPOSTHandler")
authed, err := oauth.Authed(c, true, true, true, true)

View file

@ -23,104 +23,139 @@ import (
"net"
)
// Account represents a mastodon-api Account object, as described here: https://docs.joinmastodon.org/entities/account/
// Account represents a fediverse account of some kind, either a remote one or one on this instance.
//
// swagger:model account
type Account struct {
// The account id
// The account id.
// example: 01FBVD42CQ3ZEEVMW180SBX03B
ID string `json:"id"`
// The username of the account, not including domain.
// example: some_user
Username string `json:"username"`
// The Webfinger account URI. Equal to username for local users, or username@domain for remote users.
// The account URI as discovered via webfinger.
// Equal to username for local users, or username@domain for remote users.
// example: some_user@example.org
Acct string `json:"acct"`
// The profile's display name.
// The account's display name.
// example: big jeff (he/him)
DisplayName string `json:"display_name"`
// Whether the account manually approves follow requests.
// Account manually approves follow requests.
Locked bool `json:"locked"`
// Whether the account has opted into discovery features such as the profile directory.
// Account has opted into discovery features such as the profile directory.
Discoverable bool `json:"discoverable,omitempty"`
// A presentational flag. Indicates that the account may perform automated actions, may not be monitored, or identifies as a robot.
// Account identifies as a bot.
Bot bool `json:"bot"`
// When the account was created. (ISO 8601 Datetime)
// When the account was created (ISO 8601 Datetime).
// example: 2021-07-30T09:20:25+00:00
CreatedAt string `json:"created_at"`
// The profile's bio / description.
// Bio/description of this account.
Note string `json:"note"`
// The location of the user's profile page.
// Web location of the account's profile page.
// example: https://example.org/@some_user
URL string `json:"url"`
// An image icon that is shown next to statuses and in the profile.
// Web location of the account's avatar.
// example: https://example.org/media/some_user/avatar/original/avatar.jpeg
Avatar string `json:"avatar"`
// A static version of the avatar. Equal to avatar if its value is a static image; different if avatar is an animated GIF.
// Web location of a static version of the account's avatar.
// Only relevant when the account's main avatar is a video or a gif.
// example: https://example.org/media/some_user/avatar/static/avatar.png
AvatarStatic string `json:"avatar_static"`
// An image banner that is shown above the profile and in profile cards.
// Web location of the account's header image.
// example: https://example.org/media/some_user/header/original/header.jpeg
Header string `json:"header"`
// A static version of the header. Equal to header if its value is a static image; different if header is an animated GIF.
// Web location of a static version of the account's header.
// Only relevant when the account's main header is a video or a gif.
// example: https://example.org/media/some_user/header/static/header.png
HeaderStatic string `json:"header_static"`
// The reported followers of this profile.
// Number of accounts following this account, according to our instance.
FollowersCount int `json:"followers_count"`
// The reported follows of this profile.
// Number of account's followed by this account, according to our instance.
FollowingCount int `json:"following_count"`
// How many statuses are attached to this account.
// Number of statuses posted by this account, according to our instance.
StatusesCount int `json:"statuses_count"`
// When the most recent status was posted. (ISO 8601 Datetime)
// When the account's most recent status was posted (ISO 8601 Datetime).
// example: 2021-07-30T09:20:25+00:00
LastStatusAt string `json:"last_status_at"`
// Custom emoji entities to be used when rendering the profile. If none, an empty array will be returned.
// Array of custom emojis used in this account's note or display name.
Emojis []Emoji `json:"emojis"`
// Additional metadata attached to a profile as name-value pairs.
// Additional metadata attached to this account's profile.
Fields []Field `json:"fields"`
// An extra entity returned when an account is suspended.
// Account has been suspended by our instance.
Suspended bool `json:"suspended,omitempty"`
// When a timed mute will expire, if applicable. (ISO 8601 Datetime)
// If this account has been muted, when will the mute expire (ISO 8601 Datetime).
// example: 2021-07-30T09:20:25+00:00
MuteExpiresAt string `json:"mute_expires_at,omitempty"`
// An extra entity to be used with API methods to verify credentials and update credentials.
// Extra profile information. Shown only if the requester owns the account being requested.
Source *Source `json:"source,omitempty"`
}
// AccountCreateRequest represents the form submitted during a POST request to /api/v1/accounts.
// See https://docs.joinmastodon.org/methods/accounts/
//
// swagger:model accountCreateRequest
type AccountCreateRequest struct {
// Text that will be reviewed by moderators if registrations require manual approval.
Reason string `form:"reason" json:"reason" xml:"reason"`
// The desired username for the account
// The desired username for the account.
// swagger:parameters
// pattern: [a-z0-9_]{2,64}
// example: a_valid_username
// required: true
Username string `form:"username" json:"username" xml:"username" binding:"required"`
// The email address to be used for login
// The email address to be used for login.
// swagger:parameters
// example: someone@wherever.com
// required: true
Email string `form:"email" json:"email" xml:"email" binding:"required"`
// The password to be used for login
// The password to be used for login. This will be hashed before storage.
// swagger:parameters
// example: some_really_really_really_strong_password
// required: true
Password string `form:"password" json:"password" xml:"password" binding:"required"`
// Whether the user agrees to the local rules, terms, and policies.
// These should be presented to the user in order to allow them to consent before setting this parameter to TRUE.
// The user agrees to the terms, conditions, and policies of the instance.
// swagger:parameters
// required: true
Agreement bool `form:"agreement" json:"agreement" xml:"agreement" binding:"required"`
// The language of the confirmation email that will be sent
// The language of the confirmation email that will be sent.
// swagger:parameters
// example: en
// Required: true
Locale string `form:"locale" json:"locale" xml:"locale" binding:"required"`
// The IP of the sign up request, will not be parsed from the form but must be added manually
// The IP of the sign up request, will not be parsed from the form.
// swagger:parameters
// swagger:ignore
IP net.IP `form:"-"`
}
// UpdateCredentialsRequest represents the form submitted during a PATCH request to /api/v1/accounts/update_credentials.
// See https://docs.joinmastodon.org/methods/accounts/
// swagger:ignore
type UpdateCredentialsRequest struct {
// Whether the account should be shown in the profile directory.
// Account should be made discoverable and shown in the profile directory (if enabled).
Discoverable *bool `form:"discoverable" json:"discoverable" xml:"discoverable"`
// Whether the account has a bot flag.
// Account is flagged as a bot.
Bot *bool `form:"bot" json:"bot" xml:"bot"`
// The display name to use for the profile.
// The display name to use for the account.
DisplayName *string `form:"display_name" json:"display_name" xml:"display_name"`
// The account bio.
// Bio/description of this account.
Note *string `form:"note" json:"note" xml:"note"`
// Avatar image encoded using multipart/form-data
// Avatar image encoded using multipart/form-data.
Avatar *multipart.FileHeader `form:"avatar" json:"avatar" xml:"avatar"`
// Header image encoded using multipart/form-data
Header *multipart.FileHeader `form:"header" json:"header" xml:"header"`
// Whether manual approval of follow requests is required.
// Require manual approval of follow requests.
Locked *bool `form:"locked" json:"locked" xml:"locked"`
// New Source values for this account
// New Source values for this account.
Source *UpdateSource `form:"source" json:"source" xml:"source"`
// Profile metadata name and value
FieldsAttributes *[]UpdateField `form:"fields_attributes" json:"fields_attributes" xml:"fields_attributes"`
}
// UpdateSource is to be used specifically in an UpdateCredentialsRequest.
// swagger:ignore
type UpdateSource struct {
// Default post privacy for authored statuses.
Privacy *string `form:"privacy" json:"privacy" xml:"privacy"`
// Whether to mark authored statuses as sensitive by default.
// Mark authored statuses as sensitive by default.
Sensitive *bool `form:"sensitive" json:"sensitive" xml:"sensitive"`
// Default language to use for authored statuses. (ISO 6391)
Language *string `form:"language" json:"language" xml:"language"`
@ -128,6 +163,8 @@ type UpdateSource struct {
// UpdateField is to be used specifically in an UpdateCredentialsRequest.
// By default, max 4 fields and 255 characters per property/value.
//
// swagger:model updateField
type UpdateField struct {
// Name of the field
Name *string `form:"name" json:"name" xml:"name"`
@ -136,6 +173,8 @@ type UpdateField struct {
}
// AccountFollowRequest is for parsing requests at /api/v1/accounts/:id/follow
//
// swagger:model accountFollowRequest
type AccountFollowRequest struct {
// ID of the account to follow request
// This should be a URL parameter not a form field

View file

@ -18,23 +18,28 @@
package model
// Application represents a mastodon-api Application, as defined here: https://docs.joinmastodon.org/entities/application/.
// Application represents an api Application, as defined here.
// Primarily, application is used for allowing apps like Tusky etc to connect to Mastodon on behalf of a user.
// See https://docs.joinmastodon.org/methods/apps/
//
// swagger:model application
type Application struct {
// The application ID in the db
// The ID of the application.
// example: 01FBVD42CQ3ZEEVMW180SBX03B
ID string `json:"id,omitempty"`
// The name of your application.
// The name of the application.
// example: Tusky
Name string `json:"name"`
// The website associated with your application (url)
// The website associated with the application (url)
// example: https://tusky.app
Website string `json:"website,omitempty"`
// Where the user should be redirected after authorization.
// Post-authorization redirect URI for the application (OAuth2).
// example: https://example.org/callback?some=query
RedirectURI string `json:"redirect_uri,omitempty"`
// ClientID to use when obtaining an oauth token for this application (ie., in client_id parameter of https://docs.joinmastodon.org/methods/apps/)
// Client ID associated with this application.
ClientID string `json:"client_id,omitempty"`
// Client secret to use when obtaining an auth token for this application (ie., in client_secret parameter of https://docs.joinmastodon.org/methods/apps/)
// Client secret associated with this application.
ClientSecret string `json:"client_secret,omitempty"`
// Used for Push Streaming API. Returned with POST /api/v1/apps. Equivalent to https://docs.joinmastodon.org/entities/pushsubscription/#server_key
// Push API key for this application.
VapidKey string `json:"vapid_key,omitempty"`
}

View file

@ -36,9 +36,10 @@ type AttachmentUpdateRequest struct {
}
// Attachment represents the object returned to a client after a successful media upload request.
// See: https://docs.joinmastodon.org/methods/statuses/media/
//
// swagger:model attachment
type Attachment struct {
// The ID of the attachment in the database.
// The ID of the attachment.
ID string `json:"id"`
// The type of the attachment.
// unknown = unsupported or unrecognized file type.
@ -46,23 +47,28 @@ type Attachment struct {
// gifv = Looping, soundless animation.
// video = Video clip.
// audio = Audio track.
// example: image
Type string `json:"type"`
// The location of the original full-size attachment.
// example: https://example.org/fileserver/some_id/attachments/some_id/original/attachment.jpeg
URL string `json:"url"`
// The location of a scaled-down preview of the attachment.
// example: https://example.org/fileserver/some_id/attachments/some_id/small/attachment.jpeg
PreviewURL string `json:"preview_url"`
// The location of the full-size original attachment on the remote server.
// Only defined for instances other than our own.
// example: https://some-other-server.org/attachments/original/ahhhhh.jpeg
RemoteURL string `json:"remote_url,omitempty"`
// The location of a scaled-down preview of the attachment on the remote server.
// Only defined for instances other than our own.
// example: https://some-other-server.org/attachments/small/ahhhhh.jpeg
PreviewRemoteURL string `json:"preview_remote_url,omitempty"`
// A shorter URL for the attachment.
TextURL string `json:"text_url,omitempty"`
// Metadata returned by Paperclip.
// May contain subtrees small and original, as well as various other top-level properties.
// More importantly, there may be another top-level focus Hash object as of 2.3.0, with coordinates can be used for smart thumbnail cropping.
// See https://docs.joinmastodon.org/methods/statuses/media/#focal-points points for more.
// Metadata for this attachment.
Meta MediaMeta `json:"meta,omitempty"`
// Alternate text that describes what is in the media attachment, to be used for the visually impaired or when media attachments do not load.
// Alt text that describes what is in the media attachment.
// example: This is a picture of a kitten.
Description string `json:"description,omitempty"`
// A hash computed by the BlurHash algorithm, for generating colorful preview thumbnails when media has not been downloaded yet.
// See https://github.com/woltapp/blurhash
@ -70,6 +76,8 @@ type Attachment struct {
}
// MediaMeta describes the returned media
//
// swagger:model mediaMeta
type MediaMeta struct {
Length string `json:"length,omitempty"`
Duration float32 `json:"duration,omitempty"`
@ -87,12 +95,16 @@ type MediaMeta struct {
}
// MediaFocus describes the focal point of a piece of media. It should be returned to the caller as part of MediaMeta.
//
// swagger:model mediaFocus
type MediaFocus struct {
X float32 `json:"x"` // should be between -1 and 1
Y float32 `json:"y"` // should be between -1 and 1
}
// MediaDimensions describes the physical properties of a piece of media. It should be returned to the caller as part of MediaMeta.
//
// swagger:model mediaDimensions
type MediaDimensions struct {
Width int `json:"width,omitempty"`
Height int `json:"height,omitempty"`

View file

@ -18,15 +18,18 @@
package model
// Card represents a rich preview card that is generated using OpenGraph tags from a URL. See here: https://docs.joinmastodon.org/entities/card/
// Card represents a rich preview card that is generated using OpenGraph tags from a URL.
//
// swagger:model card
type Card struct {
// REQUIRED
// Location of linked resource.
// example: https://buzzfeed.com/some/fuckin/buzzfeed/article
URL string `json:"url"`
// Title of linked resource.
// example: Buzzfeed - Is Water Wet?
Title string `json:"title"`
// Description of preview.
// example: Is water wet? We're not sure. In this article, we ask an expert...
Description string `json:"description"`
// The type of the preview card.
// String (Enumerable, oneOf)
@ -34,17 +37,19 @@ type Card struct {
// photo = Photo OEmbed
// video = Video OEmbed
// rich = iframe OEmbed. Not currently accepted, so won't show up in practice.
// example: link
Type string `json:"type"`
// OPTIONAL
// The author of the original resource.
// example: weewee@buzzfeed.com
AuthorName string `json:"author_name"`
// A link to the author of the original resource.
// example: https://buzzfeed.com/authors/weewee
AuthorURL string `json:"author_url"`
// The provider of the original resource.
// example: Buzzfeed
ProviderName string `json:"provider_name"`
// A link to the provider of the original resource.
// example: https://buzzfeed.com
ProviderURL string `json:"provider_url"`
// HTML to be used for generating the preview card.
HTML string `json:"html"`
@ -53,6 +58,7 @@ type Card struct {
// Height of preview, in pixels.
Height int `json:"height"`
// Preview thumbnail.
// example: https://example.org/fileserver/preview/thumb.jpg
Image string `json:"image"`
// Used for photo embeds, instead of custom html.
EmbedURL string `json:"embed_url"`

View file

@ -21,18 +21,40 @@ package model
import "mime/multipart"
// DomainBlock represents a block on one domain
//
// swagger:model domainBlock
type DomainBlock struct {
ID string `json:"id,omitempty"`
Domain string `form:"domain" json:"domain" validation:"required"`
Obfuscate bool `json:"obfuscate,omitempty"`
// The ID of the domain block.
// example: 01FBW21XJA09XYX51KV5JVBW0F
// readonly: true
ID string `json:"id,omitempty"`
// The hostname of the blocked domain.
// example: example.org
Domain string `form:"domain" json:"domain" validation:"required"`
// Obfuscate the domain name when serving this domain block publicly.
// A useful anti-harassment tool.
// example: false
Obfuscate bool `json:"obfuscate,omitempty"`
// Private comment for this block, visible to our instance admins only.
// example: they are poopoo
PrivateComment string `json:"private_comment,omitempty"`
PublicComment string `form:"public_comment" json:"public_comment,omitempty"`
// Public comment for this block, visible if domain blocks are served publicly.
// example: they smell
PublicComment string `form:"public_comment" json:"public_comment,omitempty"`
// The ID of the subscription that created/caused this domain block.
// example: 01FBW25TF5J67JW3HFHZCSD23K
SubscriptionID string `json:"subscription_id,omitempty"`
CreatedBy string `json:"created_by,omitempty"`
CreatedAt string `json:"created_at,omitempty"`
// ID of the account that created this domain block.
// example: 01FBW2758ZB6PBR200YPDDJK4C
CreatedBy string `json:"created_by,omitempty"`
// Time at which this block was created (ISO 8601 Datetime).
// example: 2021-07-30T09:20:25+00:00
CreatedAt string `json:"created_at,omitempty"`
}
// DomainBlockCreateRequest is the form submitted as a POST to /api/v1/admin/domain_blocks to create a new block.
//
// swagger:model domainBlockCreateRequest
type DomainBlockCreateRequest struct {
// A list of domains to block. Only used if import=true is specified.
Domains *multipart.FileHeader `form:"domains" json:"domains" xml:"domains"`

View file

@ -20,28 +20,32 @@ package model
import "mime/multipart"
// Emoji represents a custom emoji. See https://docs.joinmastodon.org/entities/emoji/
// Emoji represents a custom emoji.
//
// swagger:model emoji
type Emoji struct {
// REQUIRED
// The name of the custom emoji.
// example: blobcat_uwu
Shortcode string `json:"shortcode"`
// A link to the custom emoji.
// Web URL of the custom emoji.
// example: https://example.org/fileserver/emojis/blogcat_uwu.gif
URL string `json:"url"`
// A link to a static copy of the custom emoji.
// example: https://example.org/fileserver/emojis/blogcat_uwu.png
StaticURL string `json:"static_url"`
// Whether this Emoji should be visible in the picker or unlisted.
// Emoji is visible in the emoji picker of the instance.
// example: true
VisibleInPicker bool `json:"visible_in_picker"`
// OPTIONAL
// Used for sorting custom emoji in the picker.
// example: blobcats
Category string `json:"category,omitempty"`
}
// EmojiCreateRequest represents a request to create a custom emoji made through the admin API.
// swagger:model emojiCreateRequest
type EmojiCreateRequest struct {
// Desired shortcode for the emoji, without surrounding colons. This must be unique for the domain.
// example: blobcat_uwu
Shortcode string `form:"shortcode" validation:"required"`
// Image file to use for the emoji. Must be png or gif and no larger than 50kb.
Image *multipart.FileHeader `form:"image" validation:"required"`

View file

@ -18,16 +18,17 @@
package model
// Field represents a profile field as a name-value pair with optional verification. See https://docs.joinmastodon.org/entities/field/
// Field represents a name/value pair to display on an account's profile.
//
// swagger:model field
type Field struct {
// REQUIRED
// The key of a given field's key-value pair.
// The key/name of this field.
// example: pronouns
Name string `json:"name"`
// The value associated with the name key.
// The value of this field.
// example: they/them
Value string `json:"value"`
// OPTIONAL
// Timestamp of when the server verified a URL value for a rel="me” link. String (ISO 8601 Datetime) if value is a verified URL
// If this field has been verified, when did this occur? (ISO 8601 Datetime).
// example: 2021-07-30T09:20:25+00:00
VerifiedAt string `json:"verified_at,omitempty"`
}

View file

@ -18,14 +18,19 @@
package model
// Mention represents the mastodon-api mention type, as documented here: https://docs.joinmastodon.org/entities/mention/
// Mention represents a mention of another account.
type Mention struct {
// The account id of the mentioned user.
// The ID of the mentioned account.
// example: 01FBYJHQWQZAVWFRK9PDYTKGMB
ID string `json:"id"`
// The username of the mentioned user.
// The username of the mentioned account.
// example: some_user
Username string `json:"username"`
// The location of the mentioned user's profile.
// The web URL of the mentioned account's profile.
// example: https://example.org/@some_user
URL string `json:"url"`
// The webfinger acct: URI of the mentioned user. Equivalent to username for local users, or username@domain for remote users.
// The account URI as discovered via webfinger.
// Equal to username for local users, or username@domain for remote users.
// example: some_user@example.org
Acct string `json:"acct"`
}

View file

@ -18,12 +18,15 @@
package model
// Poll represents the mastodon-api poll type, as described here: https://docs.joinmastodon.org/entities/poll/
// Poll represents a poll attached to a status.
//
// swagger:model poll
type Poll struct {
// The ID of the poll in the database.
// example: 01FBYKMD1KBMJ0W6JF1YZ3VY5D
ID string `json:"id"`
// When the poll ends. (ISO 8601 Datetime), or null if the poll does not end
ExpiresAt string `json:"expires_at"`
ExpiresAt string `json:"expires_at,omitempty"`
// Is the poll currently expired?
Expired bool `json:"expired"`
// Does the poll allow multiple-choice answers?
@ -42,7 +45,9 @@ type Poll struct {
Emojis []Emoji `json:"emojis"`
}
// PollOptions represents the current vote counts for different poll options
// PollOptions represents the current vote counts for different poll options.
//
// swagger:model pollOptions
type PollOptions struct {
// The text value of the poll option. String.
Title string `json:"title"`

View file

@ -18,31 +18,34 @@
package model
// Relationship represents a relationship between accounts. See https://docs.joinmastodon.org/entities/relationship/
// Relationship represents a relationship between accounts.
//
// swagger:model accountRelationship
type Relationship struct {
// The account id.
// example: 01FBW9XGEP7G6K88VY4S9MPE1R
ID string `json:"id"`
// Are you following this user?
// You are following this account.
Following bool `json:"following"`
// Are you receiving this user's boosts in your home timeline?
// You are seeing reblogs/boosts from this account in your home timeline.
ShowingReblogs bool `json:"showing_reblogs"`
// Have you enabled notifications for this user?
// You are seeing notifications when this account posts.
Notifying bool `json:"notifying"`
// Are you followed by this user?
// This account follows you.
FollowedBy bool `json:"followed_by"`
// Are you blocking this user?
// You are blocking this account.
Blocking bool `json:"blocking"`
// Is this user blocking you?
// This account is blocking you.
BlockedBy bool `json:"blocked_by"`
// Are you muting this user?
// You are muting this account.
Muting bool `json:"muting"`
// Are you muting notifications from this user?
// You are muting notifications from this account.
MutingNotifications bool `json:"muting_notifications"`
// Do you have a pending follow request for this user?
// You have requested to follow this account, and the request is pending.
Requested bool `json:"requested"`
// Are you blocking this user's domain?
// You are blocking this account's domain.
DomainBlocking bool `json:"domain_blocking"`
// Are you featuring this user on your profile?
// You are featuring this account on your profile.
Endorsed bool `json:"endorsed"`
// Your note on this account.
Note string `json:"note"`

View file

@ -18,49 +18,62 @@
package model
// Status represents a mastodon-api Status type, as defined here: https://docs.joinmastodon.org/entities/status/
// Status represents a status or post.
//
// swagger:model status
type Status struct {
// ID of the status in the database.
// ID of the status.
// example: 01FBVD42CQ3ZEEVMW180SBX03B
ID string `json:"id"`
// The date when this status was created (ISO 8601 Datetime)
// The date when this status was created (ISO 8601 Datetime).
// example: 2021-07-30T09:20:25+00:00
CreatedAt string `json:"created_at"`
// ID of the status being replied.
// ID of the status being replied to.
// example: 01FBVD42CQ3ZEEVMW180SBX03B
InReplyToID string `json:"in_reply_to_id,omitempty"`
// ID of the account being replied to.
// example: 01FBVD42CQ3ZEEVMW180SBX03B
InReplyToAccountID string `json:"in_reply_to_account_id,omitempty"`
// Is this status marked as sensitive content?
// Status contains sensitive content.
// example: false
Sensitive bool `json:"sensitive"`
// Subject or summary line, below which status content is collapsed until expanded.
// Subject, summary, or content warning for the status.
// example: warning nsfw
SpoilerText string `json:"spoiler_text"`
// Visibility of this status.
// example: unlisted
Visibility Visibility `json:"visibility"`
// Primary language of this status. (ISO 639 Part 1 two-letter language code)
// Primary language of this status (ISO 639 Part 1 two-letter language code).
// example: en
Language string `json:"language"`
// URI of the status used for federation.
// ActivityPub URI of the status. Equivalent to the status's activitypub ID.
// example: https://example.org/users/some_user/statuses/01FBVD42CQ3ZEEVMW180SBX03B
URI string `json:"uri"`
// A link to the status's HTML representation.
// The status's publicly available web URL. This link will only work if the visibility of the status is 'public'.
// example: https://example.org/@some_user/statuses/01FBVD42CQ3ZEEVMW180SBX03B
URL string `json:"url"`
// How many replies this status has received.
// Number of replies to this status, according to our instance.
RepliesCount int `json:"replies_count"`
// How many boosts this status has received.
// Number of times this status has been boosted/reblogged, according to our instance.
ReblogsCount int `json:"reblogs_count"`
// How many favourites this status has received.
// Number of favourites/likes this status has received, according to our instance.
FavouritesCount int `json:"favourites_count"`
// Have you favourited this status?
// This status has been favourited by the account viewing it.
Favourited bool `json:"favourited"`
// Have you boosted this status?
// This status has been boosted/reblogged by the account viewing it.
Reblogged bool `json:"reblogged"`
// Have you muted notifications for this status's conversation?
// Replies to this status have been muted by the account viewing it.
Muted bool `json:"muted"`
// Have you bookmarked this status?
// This status has been bookmarked by the account viewing it.
Bookmarked bool `json:"bookmarked"`
// Have you pinned this status? Only appears if the status is pinnable.
// This status has been pinned by the account viewing it (only relevant for your own statuses).
Pinned bool `json:"pinned,omitempty"`
// HTML-encoded status content.
// The content of this status. Should be HTML, but might also be plaintext in some cases.
// example: <p>Hey this is a status!</p>
Content string `json:"content"`
// The status being reblogged.
// The status that this status is a reblog/boost of.
Reblog *Status `json:"reblog,omitempty"`
// The application used to post this status.
// The application used to post this status, if visible.
Application *Application `json:"application"`
// The account that authored this status.
Account *Account `json:"account"`
@ -108,17 +121,21 @@ type StatusCreateRequest struct {
Format StatusFormat `form:"format" json:"format" xml:"format"`
}
// Visibility denotes the visibility of this status to other users
// Visibility denotes the visibility of a status to other users.
//
// swagger:model statusVisibility
type Visibility string
const (
// VisibilityPublic means visible to everyone
// VisibilityPublic is visible to everyone, and will be available via the web even for nonauthenticated users.
VisibilityPublic Visibility = "public"
// VisibilityUnlisted means visible to everyone but only on home timelines or in lists
// VisibilityUnlisted is visible to everyone, but only on home timelines, lists, etc.
VisibilityUnlisted Visibility = "unlisted"
// VisibilityPrivate means visible to followers only
// VisibilityPrivate is visible only to followers of the account that posted the status.
VisibilityPrivate Visibility = "private"
// VisibilityDirect means visible only to tagged recipients
// VisibilityMutualsOnly is visible only to mutual followers of the account that posted the status.
VisibilityMutualsOnly Visibility = "mutuals_only"
// VisibilityDirect is visible only to accounts tagged in the status. It is equivalent to a direct message.
VisibilityDirect Visibility = "direct"
)

View file

@ -18,10 +18,14 @@
package model
// Tag represents a hashtag used within the content of a status. See https://docs.joinmastodon.org/entities/tag/
// Tag represents a hashtag used within the content of a status.
//
// swagger:model tag
type Tag struct {
// The value of the hashtag after the # sign.
// example: helloworld
Name string `json:"name"`
// A link to the hashtag on the instance.
// Web link to the hashtag.
// example: https://example.org/tags/helloworld
URL string `json:"url"`
}

View file

@ -18,14 +18,19 @@
package model
// Token represents an OAuth token used for authenticating with the API and performing actions.. See https://docs.joinmastodon.org/entities/token/
// Token represents an OAuth token used for authenticating with the GoToSocial API and performing actions.
//
// swagger:model oauthToken
type Token struct {
// An OAuth token to be used for authorization.
// Access token used for authorization.
AccessToken string `json:"access_token"`
// The OAuth token type. Mastodon uses Bearer tokens.
// OAuth token type. Will always be 'Bearer'.
// example: bearer
TokenType string `json:"token_type"`
// The OAuth scopes granted by this token, space-separated.
// OAuth scopes granted by this token, space-separated.
// example: read write admin
Scope string `json:"scope"`
// When the token was generated. (UNIX timestamp seconds)
// When the OAuth token was generated (UNIX timestamp seconds).
// example: 1627644520
CreatedAt int64 `json:"created_at"`
}

View file

@ -16,16 +16,4 @@
along with this program. If not, see <http://www.gnu.org/licenses/>.
*/
package model
// Activity represents the mastodon-api Activity type. See here: https://docs.joinmastodon.org/entities/activity/
type Activity struct {
// Midnight at the first day of the week. (UNIX Timestamp as string)
Week string `json:"week"`
// Statuses created since the week began. Integer cast to string.
Statuses string `json:"statuses"`
// User logins since the week began. Integer cast as string.
Logins string `json:"logins"`
// User registrations since the week began. Integer cast as string.
Registrations string `json:"registrations"`
}
package gtserror

3
lint.sh Executable file
View file

@ -0,0 +1,3 @@
#!/bin/bash
golangci-lint run

View file

@ -1,4 +1,12 @@
site_name: GoToSocial Documentation
theme: readthedocs
repo_url: https://github.com/superseriousbusiness/gotosocial
copyright: GoToSocial is licensed under the GNU AGPL v3 LICENSE. Copyright (C) 2021 the GoToSocial Authors.
copyright: GoToSocial is licensed under the GNU AGPL v3 LICENSE. Copyright (C) 2021 the GoToSocial Authors.
plugins:
- render_swagger
extra_javascript:
- assets/js/swagger-ui-bundle.js
extra_css:
- assets/css/swagger-ui.css