1 # Pleroma: A lightweight social networking server
2 # Copyright © 2017-2020 Pleroma Authors <https://pleroma.social/>
3 # SPDX-License-Identifier: AGPL-3.0-only
5 defmodule Pleroma.Web.ApiSpec.AccountOperation do
6 alias OpenApiSpex.Operation
7 alias OpenApiSpex.Reference
8 alias OpenApiSpex.Schema
9 alias Pleroma.Web.ApiSpec.Schemas.Account
10 alias Pleroma.Web.ApiSpec.Schemas.AccountRelationship
11 alias Pleroma.Web.ApiSpec.Schemas.ActorType
12 alias Pleroma.Web.ApiSpec.Schemas.ApiError
13 alias Pleroma.Web.ApiSpec.Schemas.BooleanLike
14 alias Pleroma.Web.ApiSpec.Schemas.List
15 alias Pleroma.Web.ApiSpec.Schemas.Status
16 alias Pleroma.Web.ApiSpec.Schemas.VisibilityScope
18 import Pleroma.Web.ApiSpec.Helpers
20 @spec open_api_operation(atom) :: Operation.t()
21 def open_api_operation(action) do
22 operation = String.to_existing_atom("#{action}_operation")
23 apply(__MODULE__, operation, [])
26 @spec create_operation() :: Operation.t()
27 def create_operation do
30 summary: "Register an account",
32 "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.",
33 operationId: "AccountController.create",
34 requestBody: request_body("Parameters", create_request(), required: true),
36 200 => Operation.response("Account", "application/json", create_response()),
37 400 => Operation.response("Error", "application/json", ApiError),
38 403 => Operation.response("Error", "application/json", ApiError),
39 429 => Operation.response("Error", "application/json", ApiError)
44 def verify_credentials_operation do
47 description: "Test to make sure that the user token works.",
48 summary: "Verify account credentials",
49 operationId: "AccountController.verify_credentials",
50 security: [%{"oAuth" => ["read:accounts"]}],
52 200 => Operation.response("Account", "application/json", Account)
57 def update_credentials_operation do
60 summary: "Update account credentials",
61 description: "Update the user's display and preferences.",
62 operationId: "AccountController.update_credentials",
63 security: [%{"oAuth" => ["write:accounts"]}],
64 requestBody: request_body("Parameters", update_creadentials_request(), required: true),
66 200 => Operation.response("Account", "application/json", Account),
67 403 => Operation.response("Error", "application/json", ApiError)
72 def relationships_operation do
75 summary: "Check relationships to other accounts",
76 operationId: "AccountController.relationships",
77 description: "Find out whether a given account is followed, blocked, muted, etc.",
78 security: [%{"oAuth" => ["read:follows"]}],
84 oneOf: [%Schema{type: :array, items: %Schema{type: :string}}, %Schema{type: :string}]
91 200 => Operation.response("Account", "application/json", array_of_relationships())
100 operationId: "AccountController.show",
101 description: "View information about a profile.",
102 parameters: [%Reference{"$ref": "#/components/parameters/accountIdOrNickname"}],
104 200 => Operation.response("Account", "application/json", Account),
105 404 => Operation.response("Error", "application/json", ApiError)
110 def statuses_operation do
114 operationId: "AccountController.statuses",
116 "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)",
119 %Reference{"$ref": "#/components/parameters/accountIdOrNickname"},
120 Operation.parameter(:pinned, :query, BooleanLike, "Include only pinned statuses"),
121 Operation.parameter(:tagged, :query, :string, "With tag"),
126 "Include only statuses with media attached"
132 "Include statuses from muted acccounts."
134 Operation.parameter(:exclude_reblogs, :query, BooleanLike, "Exclude reblogs"),
135 Operation.parameter(:exclude_replies, :query, BooleanLike, "Exclude replies"),
137 :exclude_visibilities,
139 %Schema{type: :array, items: VisibilityScope},
140 "Exclude visibilities"
142 ] ++ pagination_params(),
144 200 => Operation.response("Statuses", "application/json", array_of_statuses()),
145 404 => Operation.response("Error", "application/json", ApiError)
150 def followers_operation do
153 summary: "Followers",
154 operationId: "AccountController.followers",
155 security: [%{"oAuth" => ["read:accounts"]}],
157 "Accounts which follow the given account, if network is not hidden by the account owner.",
159 %Reference{"$ref": "#/components/parameters/accountIdOrNickname"},
160 with_relationships_param() | pagination_params()
163 200 => Operation.response("Accounts", "application/json", array_of_accounts())
168 def following_operation do
171 summary: "Following",
172 operationId: "AccountController.following",
173 security: [%{"oAuth" => ["read:accounts"]}],
175 "Accounts which the given account is following, if network is not hidden by the account owner.",
177 %Reference{"$ref": "#/components/parameters/accountIdOrNickname"},
178 with_relationships_param() | pagination_params()
180 responses: %{200 => Operation.response("Accounts", "application/json", array_of_accounts())}
184 def lists_operation do
187 summary: "Lists containing this account",
188 operationId: "AccountController.lists",
189 security: [%{"oAuth" => ["read:lists"]}],
190 description: "User lists that you have added this account to.",
191 parameters: [%Reference{"$ref": "#/components/parameters/accountIdOrNickname"}],
192 responses: %{200 => Operation.response("Lists", "application/json", array_of_lists())}
196 def follow_operation do
200 operationId: "AccountController.follow",
201 security: [%{"oAuth" => ["follow", "write:follows"]}],
202 description: "Follow the given account",
204 %Reference{"$ref": "#/components/parameters/accountIdOrNickname"},
209 "Receive this account's reblogs in home timeline? Defaults to true."
213 200 => Operation.response("Relationship", "application/json", AccountRelationship),
214 400 => Operation.response("Error", "application/json", ApiError),
215 404 => Operation.response("Error", "application/json", ApiError)
220 def unfollow_operation do
224 operationId: "AccountController.unfollow",
225 security: [%{"oAuth" => ["follow", "write:follows"]}],
226 description: "Unfollow the given account",
227 parameters: [%Reference{"$ref": "#/components/parameters/accountIdOrNickname"}],
229 200 => Operation.response("Relationship", "application/json", AccountRelationship),
230 400 => Operation.response("Error", "application/json", ApiError),
231 404 => Operation.response("Error", "application/json", ApiError)
236 def mute_operation do
240 operationId: "AccountController.mute",
241 security: [%{"oAuth" => ["follow", "write:mutes"]}],
242 requestBody: request_body("Parameters", mute_request()),
244 "Mute the given account. Clients should filter statuses and notifications from this account, if received (e.g. due to a boost in the Home timeline).",
246 %Reference{"$ref": "#/components/parameters/accountIdOrNickname"},
250 %Schema{allOf: [BooleanLike], default: true},
251 "Mute notifications in addition to statuses? Defaults to `true`."
255 200 => Operation.response("Relationship", "application/json", AccountRelationship)
260 def unmute_operation do
264 operationId: "AccountController.unmute",
265 security: [%{"oAuth" => ["follow", "write:mutes"]}],
266 description: "Unmute the given account.",
267 parameters: [%Reference{"$ref": "#/components/parameters/accountIdOrNickname"}],
269 200 => Operation.response("Relationship", "application/json", AccountRelationship)
274 def block_operation do
278 operationId: "AccountController.block",
279 security: [%{"oAuth" => ["follow", "write:blocks"]}],
281 "Block the given account. Clients should filter statuses from this account if received (e.g. due to a boost in the Home timeline)",
282 parameters: [%Reference{"$ref": "#/components/parameters/accountIdOrNickname"}],
284 200 => Operation.response("Relationship", "application/json", AccountRelationship)
289 def unblock_operation do
293 operationId: "AccountController.unblock",
294 security: [%{"oAuth" => ["follow", "write:blocks"]}],
295 description: "Unblock the given account.",
296 parameters: [%Reference{"$ref": "#/components/parameters/accountIdOrNickname"}],
298 200 => Operation.response("Relationship", "application/json", AccountRelationship)
303 def follow_by_uri_operation do
306 summary: "Follow by URI",
307 operationId: "AccountController.follows",
308 security: [%{"oAuth" => ["follow", "write:follows"]}],
309 requestBody: request_body("Parameters", follow_by_uri_request(), required: true),
311 200 => Operation.response("Account", "application/json", AccountRelationship),
312 400 => Operation.response("Error", "application/json", ApiError),
313 404 => Operation.response("Error", "application/json", ApiError)
318 def mutes_operation do
321 summary: "Muted accounts",
322 operationId: "AccountController.mutes",
323 description: "Accounts the user has muted.",
324 security: [%{"oAuth" => ["follow", "read:mutes"]}],
326 200 => Operation.response("Accounts", "application/json", array_of_accounts())
331 def blocks_operation do
334 summary: "Blocked users",
335 operationId: "AccountController.blocks",
336 description: "View your blocks. See also accounts/:id/{block,unblock}",
337 security: [%{"oAuth" => ["read:blocks"]}],
339 200 => Operation.response("Accounts", "application/json", array_of_accounts())
344 def endorsements_operation do
347 summary: "Endorsements",
348 operationId: "AccountController.endorsements",
349 description: "Not implemented",
350 security: [%{"oAuth" => ["read:accounts"]}],
352 200 => empty_array_response()
357 def identity_proofs_operation do
360 summary: "Identity proofs",
361 operationId: "AccountController.identity_proofs",
362 description: "Not implemented",
364 200 => empty_array_response()
369 defp create_request do
371 title: "AccountCreateRequest",
372 description: "POST body for creating an account",
378 "Text that will be reviewed by moderators if registrations require manual approval"
380 username: %Schema{type: :string, description: "The desired username for the account"},
384 "The email address to be used for login. Required when `account_activation_required` is enabled.",
389 description: "The password to be used for login",
395 "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."
399 description: "The language of the confirmation email that will be sent"
401 # Pleroma-specific properties:
402 fullname: %Schema{type: :string, description: "Full name"},
403 bio: %Schema{type: :string, description: "Bio", default: ""},
404 captcha_solution: %Schema{
406 description: "Provider-specific captcha solution"
408 captcha_token: %Schema{type: :string, description: "Provider-specific captcha token"},
409 captcha_answer_data: %Schema{type: :string, description: "Provider-specific captcha data"},
412 description: "Invite token required when the registrations aren't public"
415 required: [:username, :password, :agreement],
417 "username" => "cofe",
418 "email" => "cofe@example.com",
419 "password" => "secret",
420 "agreement" => "true",
426 defp create_response do
428 title: "AccountCreateResponse",
429 description: "Response schema for an account",
432 token_type: %Schema{type: :string},
433 access_token: %Schema{type: :string},
434 scope: %Schema{type: :array, items: %Schema{type: :string}},
435 created_at: %Schema{type: :integer, format: :"date-time"}
438 "access_token" => "i9hAVVzGld86Pl5JtLtizKoXVvtTlSCJvwaugCxvZzk",
439 "created_at" => 1_585_918_714,
440 "scope" => ["read", "write", "follow", "push"],
441 "token_type" => "Bearer"
446 defp update_creadentials_request do
448 title: "AccountUpdateCredentialsRequest",
449 description: "POST body for creating an account",
454 description: "Whether the account has a bot flag."
456 display_name: %Schema{
458 description: "The display name to use for the profile."
460 note: %Schema{type: :string, description: "The account bio."},
463 description: "Avatar image encoded using multipart/form-data",
468 description: "Header image encoded using multipart/form-data",
473 description: "Whether manual approval of follow requests is required."
475 fields_attributes: %Schema{
477 %Schema{type: :array, items: attribute_field()},
478 %Schema{type: :object, additionalProperties: %Schema{type: attribute_field()}}
481 # NOTE: `source` field is not supported
486 # privacy: %Schema{type: :string},
487 # sensitive: %Schema{type: :boolean},
488 # language: %Schema{type: :string}
492 # Pleroma-specific fields
493 no_rich_text: %Schema{
495 description: "html tags are stripped from all statuses requested from the API"
497 hide_followers: %Schema{type: :boolean, description: "user's followers will be hidden"},
498 hide_follows: %Schema{type: :boolean, description: "user's follows will be hidden"},
499 hide_followers_count: %Schema{
501 description: "user's follower count will be hidden"
503 hide_follows_count: %Schema{
505 description: "user's follow count will be hidden"
507 hide_favorites: %Schema{
509 description: "user's favorites timeline will be hidden"
513 description: "user's role (e.g admin, moderator) will be exposed to anyone in the
516 default_scope: VisibilityScope,
517 pleroma_settings_store: %Schema{
519 description: "Opaque user settings to be saved on the backend."
521 skip_thread_containment: %Schema{
523 description: "Skip filtering out broken threads"
525 allow_following_move: %Schema{
527 description: "Allows automatically follow moved following accounts"
529 pleroma_background_image: %Schema{
531 description: "Sets the background image of the user.",
534 discoverable: %Schema{
537 "Discovery of this account in search results and other services is allowed."
539 actor_type: ActorType
543 display_name: "cofe",
545 fields_attributes: [%{name: "foo", value: "bar"}],
547 hide_followers: true,
549 hide_followers_count: false,
550 hide_follows_count: false,
551 hide_favorites: false,
553 default_scope: "private",
554 pleroma_settings_store: %{"pleroma-fe" => %{"key" => "val"}},
555 skip_thread_containment: false,
556 allow_following_move: false,
563 def array_of_accounts do
565 title: "ArrayOfAccounts",
568 example: [Account.schema().example]
572 defp array_of_relationships do
574 title: "ArrayOfRelationships",
575 description: "Response schema for account relationships",
577 items: AccountRelationship,
582 "showing_reblogs" => true,
583 "followed_by" => true,
585 "blocked_by" => true,
587 "muting_notifications" => false,
588 "requested" => false,
589 "domain_blocking" => false,
590 "subscribing" => false,
596 "showing_reblogs" => true,
597 "followed_by" => true,
599 "blocked_by" => true,
601 "muting_notifications" => false,
603 "domain_blocking" => false,
604 "subscribing" => false,
610 "showing_reblogs" => true,
611 "followed_by" => true,
613 "blocked_by" => false,
615 "muting_notifications" => false,
616 "requested" => false,
617 "domain_blocking" => true,
618 "subscribing" => true,
625 defp follow_by_uri_request do
627 title: "AccountFollowsRequest",
628 description: "POST body for muting an account",
631 uri: %Schema{type: :string, format: :uri}
639 title: "AccountMuteRequest",
640 description: "POST body for muting an account",
643 notifications: %Schema{
645 description: "Mute notifications in addition to statuses? Defaults to true.",
650 "notifications" => true
655 defp array_of_lists do
657 title: "ArrayOfLists",
658 description: "Response schema for lists",
662 %{"id" => "123", "title" => "my list"},
663 %{"id" => "1337", "title" => "anotehr list"}
668 defp array_of_statuses do
670 title: "ArrayOfStatuses",
676 defp attribute_field do
678 title: "AccountAttributeField",
679 description: "Request schema for account custom fields",
682 name: %Schema{type: :string},
683 value: %Schema{type: :string}
685 required: [:name, :value],
688 "value" => "https://pleroma.com"