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.Helpers
10 alias Pleroma.Web.ApiSpec.Schemas.Account
11 alias Pleroma.Web.ApiSpec.Schemas.AccountCreateRequest
12 alias Pleroma.Web.ApiSpec.Schemas.AccountCreateResponse
13 alias Pleroma.Web.ApiSpec.Schemas.AccountRelationship
14 alias Pleroma.Web.ApiSpec.Schemas.AccountRelationshipsResponse
15 alias Pleroma.Web.ApiSpec.Schemas.AccountsResponse
16 alias Pleroma.Web.ApiSpec.Schemas.AccountUpdateCredentialsRequest
17 alias Pleroma.Web.ApiSpec.Schemas.BooleanLike
18 alias Pleroma.Web.ApiSpec.Schemas.ListsResponse
19 alias Pleroma.Web.ApiSpec.Schemas.StatusesResponse
20 alias Pleroma.Web.ApiSpec.Schemas.VisibilityScope
22 @spec open_api_operation(atom) :: Operation.t()
23 def open_api_operation(action) do
24 operation = String.to_existing_atom("#{action}_operation")
25 apply(__MODULE__, operation, [])
28 @spec create_operation() :: Operation.t()
29 def create_operation do
32 summary: "Register an account",
34 "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.",
35 operationId: "AccountController.create",
36 requestBody: Helpers.request_body("Parameters", AccountCreateRequest, required: true),
38 200 => Operation.response("Account", "application/json", AccountCreateResponse)
43 def verify_credentials_operation do
46 description: "Test to make sure that the user token works.",
47 summary: "Verify account credentials",
48 operationId: "AccountController.verify_credentials",
49 security: [%{"oAuth" => ["read:accounts"]}],
51 200 => Operation.response("Account", "application/json", Account)
56 def update_credentials_operation do
59 summary: "Update account credentials",
60 description: "Update the user's display and preferences.",
61 operationId: "AccountController.update_credentials",
62 security: [%{"oAuth" => ["write:accounts"]}],
64 Helpers.request_body("Parameters", AccountUpdateCredentialsRequest, required: true),
66 200 => Operation.response("Account", "application/json", Account)
71 def relationships_operation do
74 summary: "Check relationships to other accounts",
75 operationId: "AccountController.relationships",
76 description: "Find out whether a given account is followed, blocked, muted, etc.",
77 security: [%{"oAuth" => ["read:follows"]}],
83 oneOf: [%Schema{type: :array, items: %Schema{type: :string}}, %Schema{type: :string}]
90 200 => Operation.response("Account", "application/json", AccountRelationshipsResponse)
99 operationId: "AccountController.show",
100 description: "View information about a profile.",
101 parameters: [%Reference{"$ref": "#/components/parameters/accountIdOrNickname"}],
103 200 => Operation.response("Account", "application/json", Account)
108 def statuses_operation do
112 operationId: "AccountController.statuses",
114 "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)",
116 %Reference{"$ref": "#/components/parameters/accountIdOrNickname"},
117 Operation.parameter(:pinned, :query, BooleanLike, "Pinned"),
118 Operation.parameter(:tagged, :query, :string, "With tag"),
119 Operation.parameter(:only_media, :query, BooleanLike, "Only meadia"),
120 Operation.parameter(:with_muted, :query, BooleanLike, "With muted"),
121 Operation.parameter(:exclude_reblogs, :query, BooleanLike, "Exclude reblobs"),
123 :exclude_visibilities,
125 %Schema{type: :array, items: VisibilityScope},
126 "Exclude visibilities"
128 Operation.parameter(:max_id, :query, :string, "Max ID"),
129 Operation.parameter(:min_id, :query, :string, "Mix ID"),
130 Operation.parameter(:since_id, :query, :string, "Since ID"),
134 %Schema{type: :integer, default: 20, maximum: 40},
139 200 => Operation.response("Statuses", "application/json", StatusesResponse)
144 def followers_operation do
147 summary: "Followers",
148 operationId: "AccountController.followers",
149 security: [%{"oAuth" => ["read:accounts"]}],
151 "Accounts which follow the given account, if network is not hidden by the account owner.",
153 %Reference{"$ref": "#/components/parameters/accountIdOrNickname"},
154 Operation.parameter(:max_id, :query, :string, "Max ID"),
155 Operation.parameter(:min_id, :query, :string, "Mix ID"),
156 Operation.parameter(:since_id, :query, :string, "Since ID"),
160 %Schema{type: :integer, default: 20, maximum: 40},
165 200 => Operation.response("Accounts", "application/json", AccountsResponse)
170 def following_operation do
173 summary: "Following",
174 operationId: "AccountController.following",
175 security: [%{"oAuth" => ["read:accounts"]}],
177 "Accounts which the given account is following, if network is not hidden by the account owner.",
179 %Reference{"$ref": "#/components/parameters/accountIdOrNickname"},
180 Operation.parameter(:max_id, :query, :string, "Max ID"),
181 Operation.parameter(:min_id, :query, :string, "Mix ID"),
182 Operation.parameter(:since_id, :query, :string, "Since ID"),
186 %Schema{type: :integer, default: 20, maximum: 40},
190 responses: %{200 => Operation.response("Accounts", "application/json", AccountsResponse)}
194 def lists_operation do
197 summary: "Lists containing this account",
198 operationId: "AccountController.lists",
199 security: [%{"oAuth" => ["read:lists"]}],
200 description: "User lists that you have added this account to.",
201 parameters: [%Reference{"$ref": "#/components/parameters/accountIdOrNickname"}],
202 responses: %{200 => Operation.response("Lists", "application/json", ListsResponse)}
206 def follow_operation do
210 operationId: "AccountController.follow",
211 security: [%{"oAuth" => ["follow", "write:follows"]}],
212 description: "Follow the given account",
214 %Reference{"$ref": "#/components/parameters/accountIdOrNickname"},
219 "Receive this account's reblogs in home timeline? Defaults to true."
223 200 => Operation.response("Relationship", "application/json", AccountRelationship)
228 def unfollow_operation do
232 operationId: "AccountController.unfollow",
233 security: [%{"oAuth" => ["follow", "write:follows"]}],
234 description: "Unfollow the given account",
235 parameters: [%Reference{"$ref": "#/components/parameters/accountIdOrNickname"}],
237 200 => Operation.response("Relationship", "application/json", AccountRelationship)
242 def mute_operation, do: :ok
243 def unmute_operation, do: :ok
244 def block_operation, do: :ok
245 def unblock_operation, do: :ok
246 def follows_operation, do: :ok
247 def mutes_operation, do: :ok
248 def blocks_operation, do: :ok
249 def endorsements_operation, do: :ok