X-Git-Url: http://git.squeep.com/?a=blobdiff_plain;ds=sidebyside;f=lib%2Fpleroma%2Fweb%2Fapi_spec%2Foperations%2Faccount_operation.ex;h=894ad5db06eda7bef1bce4f2841c227afe2ee634;hb=a079ec3a3cdfd42d2cbd51c7698c2c87828e5778;hp=aaebc9b5cb72c3e3f991f64eb14c6dc6f16fca41;hpb=70951d042b5d7b12608a3f73a73c757fc4204449;p=akkoma
diff --git a/lib/pleroma/web/api_spec/operations/account_operation.ex b/lib/pleroma/web/api_spec/operations/account_operation.ex
index aaebc9b5c..894ad5db0 100644
--- a/lib/pleroma/web/api_spec/operations/account_operation.ex
+++ b/lib/pleroma/web/api_spec/operations/account_operation.ex
@@ -1,5 +1,5 @@
# Pleroma: A lightweight social networking server
-# Copyright © 2017-2020 Pleroma Authors
+# Copyright © 2017-2021 Pleroma Authors
# SPDX-License-Identifier: AGPL-3.0-only
defmodule Pleroma.Web.ApiSpec.AccountOperation do
@@ -26,7 +26,7 @@ defmodule Pleroma.Web.ApiSpec.AccountOperation do
@spec create_operation() :: Operation.t()
def create_operation do
%Operation{
- tags: ["accounts"],
+ tags: ["Account credentials"],
summary: "Register an account",
description:
"Creates a user and account records. Returns an account access token for the app that initiated the request. The app should save this token for later, and should wait for the user to confirm their account by clicking a link in their email inbox.",
@@ -43,7 +43,7 @@ defmodule Pleroma.Web.ApiSpec.AccountOperation do
def verify_credentials_operation do
%Operation{
- tags: ["accounts"],
+ tags: ["Account credentials"],
description: "Test to make sure that the user token works.",
summary: "Verify account credentials",
operationId: "AccountController.verify_credentials",
@@ -56,7 +56,7 @@ defmodule Pleroma.Web.ApiSpec.AccountOperation do
def update_credentials_operation do
%Operation{
- tags: ["accounts"],
+ tags: ["Account credentials"],
summary: "Update account credentials",
description: "Update the user's display and preferences.",
operationId: "AccountController.update_credentials",
@@ -64,15 +64,16 @@ defmodule Pleroma.Web.ApiSpec.AccountOperation do
requestBody: request_body("Parameters", update_credentials_request(), required: true),
responses: %{
200 => Operation.response("Account", "application/json", Account),
- 403 => Operation.response("Error", "application/json", ApiError)
+ 403 => Operation.response("Error", "application/json", ApiError),
+ 413 => Operation.response("Error", "application/json", ApiError)
}
}
end
def relationships_operation do
%Operation{
- tags: ["accounts"],
- summary: "Check relationships to other accounts",
+ tags: ["Retrieve account information"],
+ summary: "Relationship with current account",
operationId: "AccountController.relationships",
description: "Find out whether a given account is followed, blocked, muted, etc.",
security: [%{"oAuth" => ["read:follows"]}],
@@ -95,11 +96,14 @@ defmodule Pleroma.Web.ApiSpec.AccountOperation do
def show_operation do
%Operation{
- tags: ["accounts"],
+ tags: ["Retrieve account information"],
summary: "Account",
operationId: "AccountController.show",
description: "View information about a profile.",
- parameters: [%Reference{"$ref": "#/components/parameters/accountIdOrNickname"}],
+ parameters: [
+ %Reference{"$ref": "#/components/parameters/accountIdOrNickname"},
+ with_relationships_param()
+ ],
responses: %{
200 => Operation.response("Account", "application/json", Account),
401 => Operation.response("Error", "application/json", ApiError),
@@ -110,8 +114,8 @@ defmodule Pleroma.Web.ApiSpec.AccountOperation do
def statuses_operation do
%Operation{
- tags: ["accounts"],
summary: "Statuses",
+ tags: ["Retrieve account information"],
operationId: "AccountController.statuses",
description:
"Statuses posted to the given account. Public (for public statuses only), or user token + `read:statuses` (for private statuses the user is authorized to see)",
@@ -130,7 +134,7 @@ defmodule Pleroma.Web.ApiSpec.AccountOperation do
:with_muted,
:query,
BooleanLike,
- "Include statuses from muted acccounts."
+ "Include statuses from muted accounts."
),
Operation.parameter(:exclude_reblogs, :query, BooleanLike, "Exclude reblogs"),
Operation.parameter(:exclude_replies, :query, BooleanLike, "Exclude replies"),
@@ -139,6 +143,12 @@ defmodule Pleroma.Web.ApiSpec.AccountOperation do
:query,
%Schema{type: :array, items: VisibilityScope},
"Exclude visibilities"
+ ),
+ Operation.parameter(
+ :with_muted,
+ :query,
+ BooleanLike,
+ "Include reactions from muted accounts."
)
] ++ pagination_params(),
responses: %{
@@ -151,7 +161,7 @@ defmodule Pleroma.Web.ApiSpec.AccountOperation do
def followers_operation do
%Operation{
- tags: ["accounts"],
+ tags: ["Retrieve account information"],
summary: "Followers",
operationId: "AccountController.followers",
security: [%{"oAuth" => ["read:accounts"]}],
@@ -170,7 +180,7 @@ defmodule Pleroma.Web.ApiSpec.AccountOperation do
def following_operation do
%Operation{
- tags: ["accounts"],
+ tags: ["Retrieve account information"],
summary: "Following",
operationId: "AccountController.following",
security: [%{"oAuth" => ["read:accounts"]}],
@@ -187,7 +197,7 @@ defmodule Pleroma.Web.ApiSpec.AccountOperation do
def lists_operation do
%Operation{
- tags: ["accounts"],
+ tags: ["Retrieve account information"],
summary: "Lists containing this account",
operationId: "AccountController.lists",
security: [%{"oAuth" => ["read:lists"]}],
@@ -199,7 +209,7 @@ defmodule Pleroma.Web.ApiSpec.AccountOperation do
def follow_operation do
%Operation{
- tags: ["accounts"],
+ tags: ["Account actions"],
summary: "Follow",
operationId: "AccountController.follow",
security: [%{"oAuth" => ["follow", "write:follows"]}],
@@ -214,9 +224,15 @@ defmodule Pleroma.Web.ApiSpec.AccountOperation do
type: :object,
properties: %{
reblogs: %Schema{
- type: :boolean,
+ allOf: [BooleanLike],
description: "Receive this account's reblogs in home timeline? Defaults to true.",
default: true
+ },
+ notify: %Schema{
+ allOf: [BooleanLike],
+ description:
+ "Receive notifications for all statuses posted by the account? Defaults to false.",
+ default: false
}
}
},
@@ -232,7 +248,7 @@ defmodule Pleroma.Web.ApiSpec.AccountOperation do
def unfollow_operation do
%Operation{
- tags: ["accounts"],
+ tags: ["Account actions"],
summary: "Unfollow",
operationId: "AccountController.unfollow",
security: [%{"oAuth" => ["follow", "write:follows"]}],
@@ -248,7 +264,7 @@ defmodule Pleroma.Web.ApiSpec.AccountOperation do
def mute_operation do
%Operation{
- tags: ["accounts"],
+ tags: ["Account actions"],
summary: "Mute",
operationId: "AccountController.mute",
security: [%{"oAuth" => ["follow", "write:mutes"]}],
@@ -262,6 +278,12 @@ defmodule Pleroma.Web.ApiSpec.AccountOperation do
:query,
%Schema{allOf: [BooleanLike], default: true},
"Mute notifications in addition to statuses? Defaults to `true`."
+ ),
+ Operation.parameter(
+ :expires_in,
+ :query,
+ %Schema{type: :integer, default: 0},
+ "Expire the mute in `expires_in` seconds. Default 0 for infinity"
)
],
responses: %{
@@ -272,7 +294,7 @@ defmodule Pleroma.Web.ApiSpec.AccountOperation do
def unmute_operation do
%Operation{
- tags: ["accounts"],
+ tags: ["Account actions"],
summary: "Unmute",
operationId: "AccountController.unmute",
security: [%{"oAuth" => ["follow", "write:mutes"]}],
@@ -286,7 +308,7 @@ defmodule Pleroma.Web.ApiSpec.AccountOperation do
def block_operation do
%Operation{
- tags: ["accounts"],
+ tags: ["Account actions"],
summary: "Block",
operationId: "AccountController.block",
security: [%{"oAuth" => ["follow", "write:blocks"]}],
@@ -301,7 +323,7 @@ defmodule Pleroma.Web.ApiSpec.AccountOperation do
def unblock_operation do
%Operation{
- tags: ["accounts"],
+ tags: ["Account actions"],
summary: "Unblock",
operationId: "AccountController.unblock",
security: [%{"oAuth" => ["follow", "write:blocks"]}],
@@ -313,9 +335,48 @@ defmodule Pleroma.Web.ApiSpec.AccountOperation do
}
end
+ def remove_from_followers_operation do
+ %Operation{
+ tags: ["Account actions"],
+ summary: "Remove from followers",
+ operationId: "AccountController.remove_from_followers",
+ security: [%{"oAuth" => ["follow", "write:follows"]}],
+ description: "Remove the given account from followers",
+ parameters: [%Reference{"$ref": "#/components/parameters/accountIdOrNickname"}],
+ responses: %{
+ 200 => Operation.response("Relationship", "application/json", AccountRelationship),
+ 400 => Operation.response("Error", "application/json", ApiError),
+ 404 => Operation.response("Error", "application/json", ApiError)
+ }
+ }
+ end
+
+ def note_operation do
+ %Operation{
+ tags: ["Account actions"],
+ summary: "Set a private note about a user.",
+ operationId: "AccountController.note",
+ security: [%{"oAuth" => ["follow", "write:accounts"]}],
+ requestBody: request_body("Parameters", note_request()),
+ description: "Create a note for the given account.",
+ parameters: [
+ %Reference{"$ref": "#/components/parameters/accountIdOrNickname"},
+ Operation.parameter(
+ :comment,
+ :query,
+ %Schema{type: :string},
+ "Account note body"
+ )
+ ],
+ responses: %{
+ 200 => Operation.response("Relationship", "application/json", AccountRelationship)
+ }
+ }
+ end
+
def follow_by_uri_operation do
%Operation{
- tags: ["accounts"],
+ tags: ["Account actions"],
summary: "Follow by URI",
operationId: "AccountController.follows",
security: [%{"oAuth" => ["follow", "write:follows"]}],
@@ -330,11 +391,12 @@ defmodule Pleroma.Web.ApiSpec.AccountOperation do
def mutes_operation do
%Operation{
- tags: ["accounts"],
- summary: "Muted accounts",
+ tags: ["Blocks and mutes"],
+ summary: "Retrieve list of mutes",
operationId: "AccountController.mutes",
description: "Accounts the user has muted.",
security: [%{"oAuth" => ["follow", "read:mutes"]}],
+ parameters: [with_relationships_param() | pagination_params()],
responses: %{
200 => Operation.response("Accounts", "application/json", array_of_accounts())
}
@@ -343,20 +405,42 @@ defmodule Pleroma.Web.ApiSpec.AccountOperation do
def blocks_operation do
%Operation{
- tags: ["accounts"],
- summary: "Blocked users",
+ tags: ["Blocks and mutes"],
+ summary: "Retrieve list of blocks",
operationId: "AccountController.blocks",
description: "View your blocks. See also accounts/:id/{block,unblock}",
security: [%{"oAuth" => ["read:blocks"]}],
+ parameters: pagination_params(),
responses: %{
200 => Operation.response("Accounts", "application/json", array_of_accounts())
}
}
end
+ def lookup_operation do
+ %Operation{
+ tags: ["Account lookup"],
+ summary: "Find a user by nickname",
+ operationId: "AccountController.lookup",
+ parameters: [
+ Operation.parameter(
+ :acct,
+ :query,
+ :string,
+ "User nickname"
+ )
+ ],
+ responses: %{
+ 200 => Operation.response("Account", "application/json", Account),
+ 401 => Operation.response("Error", "application/json", ApiError),
+ 404 => Operation.response("Error", "application/json", ApiError)
+ }
+ }
+ end
+
def endorsements_operation do
%Operation{
- tags: ["accounts"],
+ tags: ["Retrieve account information"],
summary: "Endorsements",
operationId: "AccountController.endorsements",
description: "Not implemented",
@@ -369,9 +453,13 @@ defmodule Pleroma.Web.ApiSpec.AccountOperation do
def identity_proofs_operation do
%Operation{
- tags: ["accounts"],
+ tags: ["Retrieve account information"],
summary: "Identity proofs",
operationId: "AccountController.identity_proofs",
+ # Validators complains about unused path params otherwise
+ parameters: [
+ %Reference{"$ref": "#/components/parameters/accountIdOrNickname"}
+ ],
description: "Not implemented",
responses: %{
200 => empty_array_response()
@@ -437,6 +525,11 @@ defmodule Pleroma.Web.ApiSpec.AccountOperation do
type: :string,
nullable: true,
description: "Invite token required when the registrations aren't public"
+ },
+ language: %Schema{
+ type: :string,
+ nullable: true,
+ description: "User's preferred language for emails"
}
},
example: %{
@@ -469,7 +562,6 @@ defmodule Pleroma.Web.ApiSpec.AccountOperation do
identifier: %Schema{type: :string},
message: %Schema{type: :string}
},
- required: [],
# Note: example of successful registration with failed login response:
# example: %{
# "identifier" => "missing_confirmed_email",
@@ -521,16 +613,11 @@ defmodule Pleroma.Web.ApiSpec.AccountOperation do
nullable: true,
description: "Whether manual approval of follow requests is required."
},
- accepts_chat_messages: %Schema{
- allOf: [BooleanLike],
- nullable: true,
- description: "Whether the user accepts receiving chat messages."
- },
fields_attributes: %Schema{
nullable: true,
oneOf: [
%Schema{type: :array, items: attribute_field()},
- %Schema{type: :object, additionalProperties: %Schema{type: attribute_field()}}
+ %Schema{type: :object, additionalProperties: attribute_field()}
]
},
# NOTE: `source` field is not supported
@@ -597,6 +684,12 @@ defmodule Pleroma.Web.ApiSpec.AccountOperation do
nullable: true,
description: "Allows automatically follow moved following accounts"
},
+ also_known_as: %Schema{
+ type: :array,
+ items: %Schema{type: :string},
+ nullable: true,
+ description: "List of alternate ActivityPub IDs"
+ },
pleroma_background_image: %Schema{
type: :string,
nullable: true,
@@ -607,9 +700,15 @@ defmodule Pleroma.Web.ApiSpec.AccountOperation do
allOf: [BooleanLike],
nullable: true,
description:
- "Discovery of this account in search results and other services is allowed."
+ "Discovery (listing, indexing) of this account by external services (search bots etc.) is allowed."
},
- actor_type: ActorType
+ actor_type: ActorType,
+ status_ttl_days: %Schema{
+ type: :integer,
+ nullable: true,
+ description:
+ "Number of days after which statuses will be deleted. Set to -1 to disable."
+ }
},
example: %{
bot: false,
@@ -627,8 +726,10 @@ defmodule Pleroma.Web.ApiSpec.AccountOperation do
pleroma_settings_store: %{"pleroma-fe" => %{"key" => "val"}},
skip_thread_containment: false,
allow_following_move: false,
+ also_known_as: ["https://foo.bar/users/foo"],
discoverable: false,
- actor_type: "Person"
+ actor_type: "Person",
+ status_ttl_days: 30
}
}
end
@@ -658,9 +759,11 @@ defmodule Pleroma.Web.ApiSpec.AccountOperation do
"blocked_by" => true,
"muting" => false,
"muting_notifications" => false,
+ "note" => "",
"requested" => false,
"domain_blocking" => false,
"subscribing" => false,
+ "notifying" => false,
"endorsed" => true
},
%{
@@ -672,9 +775,11 @@ defmodule Pleroma.Web.ApiSpec.AccountOperation do
"blocked_by" => true,
"muting" => true,
"muting_notifications" => false,
+ "note" => "",
"requested" => true,
"domain_blocking" => false,
"subscribing" => false,
+ "notifying" => false,
"endorsed" => false
},
%{
@@ -686,9 +791,11 @@ defmodule Pleroma.Web.ApiSpec.AccountOperation do
"blocked_by" => false,
"muting" => true,
"muting_notifications" => false,
+ "note" => "",
"requested" => false,
"domain_blocking" => true,
"subscribing" => true,
+ "notifying" => true,
"endorsed" => false
}
]
@@ -718,10 +825,34 @@ defmodule Pleroma.Web.ApiSpec.AccountOperation do
nullable: true,
description: "Mute notifications in addition to statuses? Defaults to true.",
default: true
+ },
+ expires_in: %Schema{
+ type: :integer,
+ nullable: true,
+ description: "Expire the mute in `expires_in` seconds. Default 0 for infinity",
+ default: 0
+ }
+ },
+ example: %{
+ "notifications" => true,
+ "expires_in" => 86_400
+ }
+ }
+ end
+
+ defp note_request do
+ %Schema{
+ title: "AccountNoteRequest",
+ description: "POST body for adding a note for an account",
+ type: :object,
+ properties: %{
+ comment: %Schema{
+ type: :string,
+ description: "Account note body"
}
},
example: %{
- "notifications" => true
+ "comment" => "Example note"
}
}
end