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.AccountFollowsRequest
14 alias Pleroma.Web.ApiSpec.Schemas.AccountMuteRequest
15 alias Pleroma.Web.ApiSpec.Schemas.AccountRelationship
16 alias Pleroma.Web.ApiSpec.Schemas.AccountRelationshipsResponse
17 alias Pleroma.Web.ApiSpec.Schemas.AccountsResponse
18 alias Pleroma.Web.ApiSpec.Schemas.AccountUpdateCredentialsRequest
19 alias Pleroma.Web.ApiSpec.Schemas.BooleanLike
20 alias Pleroma.Web.ApiSpec.Schemas.ListsResponse
21 alias Pleroma.Web.ApiSpec.Schemas.StatusesResponse
22 alias Pleroma.Web.ApiSpec.Schemas.VisibilityScope
24 @spec open_api_operation(atom) :: Operation.t()
25 def open_api_operation(action) do
26 operation = String.to_existing_atom("#{action}_operation")
27 apply(__MODULE__, operation, [])
30 @spec create_operation() :: Operation.t()
31 def create_operation do
34 summary: "Register an account",
36 "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.",
37 operationId: "AccountController.create",
38 requestBody: Helpers.request_body("Parameters", AccountCreateRequest, required: true),
40 200 => Operation.response("Account", "application/json", AccountCreateResponse)
45 def verify_credentials_operation do
48 description: "Test to make sure that the user token works.",
49 summary: "Verify account credentials",
50 operationId: "AccountController.verify_credentials",
51 security: [%{"oAuth" => ["read:accounts"]}],
53 200 => Operation.response("Account", "application/json", Account)
58 def update_credentials_operation do
61 summary: "Update account credentials",
62 description: "Update the user's display and preferences.",
63 operationId: "AccountController.update_credentials",
64 security: [%{"oAuth" => ["write:accounts"]}],
66 Helpers.request_body("Parameters", AccountUpdateCredentialsRequest, required: true),
68 200 => Operation.response("Account", "application/json", Account)
73 def relationships_operation do
76 summary: "Check relationships to other accounts",
77 operationId: "AccountController.relationships",
78 description: "Find out whether a given account is followed, blocked, muted, etc.",
79 security: [%{"oAuth" => ["read:follows"]}],
85 oneOf: [%Schema{type: :array, items: %Schema{type: :string}}, %Schema{type: :string}]
92 200 => Operation.response("Account", "application/json", AccountRelationshipsResponse)
101 operationId: "AccountController.show",
102 description: "View information about a profile.",
103 parameters: [%Reference{"$ref": "#/components/parameters/accountIdOrNickname"}],
105 200 => Operation.response("Account", "application/json", Account)
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)",
118 %Reference{"$ref": "#/components/parameters/accountIdOrNickname"},
119 Operation.parameter(:pinned, :query, BooleanLike, "Include only pinned statuses"),
120 Operation.parameter(:tagged, :query, :string, "With tag"),
125 "Include only statuses with media attached"
131 "Include statuses from muted acccounts."
133 Operation.parameter(:exclude_reblogs, :query, BooleanLike, "Exclude reblogs"),
135 :exclude_visibilities,
137 %Schema{type: :array, items: VisibilityScope},
138 "Exclude visibilities"
140 Operation.parameter(:max_id, :query, :string, "Return statuses older than this ID"),
145 "Return the oldest statuses newer than this ID"
151 "Return the newest statuses newer than this ID"
156 %Schema{type: :integer, default: 20, maximum: 40},
161 200 => Operation.response("Statuses", "application/json", StatusesResponse)
166 def followers_operation do
169 summary: "Followers",
170 operationId: "AccountController.followers",
171 security: [%{"oAuth" => ["read:accounts"]}],
173 "Accounts which follow the given account, if network is not hidden by the account owner.",
175 %Reference{"$ref": "#/components/parameters/accountIdOrNickname"},
176 Operation.parameter(:max_id, :query, :string, "Max ID"),
177 Operation.parameter(:min_id, :query, :string, "Mix ID"),
178 Operation.parameter(:since_id, :query, :string, "Since ID"),
182 %Schema{type: :integer, default: 20, maximum: 40},
187 200 => Operation.response("Accounts", "application/json", AccountsResponse)
192 def following_operation do
195 summary: "Following",
196 operationId: "AccountController.following",
197 security: [%{"oAuth" => ["read:accounts"]}],
199 "Accounts which the given account is following, if network is not hidden by the account owner.",
201 %Reference{"$ref": "#/components/parameters/accountIdOrNickname"},
202 Operation.parameter(:max_id, :query, :string, "Max ID"),
203 Operation.parameter(:min_id, :query, :string, "Mix ID"),
204 Operation.parameter(:since_id, :query, :string, "Since ID"),
208 %Schema{type: :integer, default: 20, maximum: 40},
212 responses: %{200 => Operation.response("Accounts", "application/json", AccountsResponse)}
216 def lists_operation do
219 summary: "Lists containing this account",
220 operationId: "AccountController.lists",
221 security: [%{"oAuth" => ["read:lists"]}],
222 description: "User lists that you have added this account to.",
223 parameters: [%Reference{"$ref": "#/components/parameters/accountIdOrNickname"}],
224 responses: %{200 => Operation.response("Lists", "application/json", ListsResponse)}
228 def follow_operation do
232 operationId: "AccountController.follow",
233 security: [%{"oAuth" => ["follow", "write:follows"]}],
234 description: "Follow the given account",
236 %Reference{"$ref": "#/components/parameters/accountIdOrNickname"},
241 "Receive this account's reblogs in home timeline? Defaults to true."
245 200 => Operation.response("Relationship", "application/json", AccountRelationship)
250 def unfollow_operation do
254 operationId: "AccountController.unfollow",
255 security: [%{"oAuth" => ["follow", "write:follows"]}],
256 description: "Unfollow the given account",
257 parameters: [%Reference{"$ref": "#/components/parameters/accountIdOrNickname"}],
259 200 => Operation.response("Relationship", "application/json", AccountRelationship)
264 def mute_operation do
268 operationId: "AccountController.mute",
269 security: [%{"oAuth" => ["follow", "write:mutes"]}],
270 requestBody: Helpers.request_body("Parameters", AccountMuteRequest),
272 "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).",
274 %Reference{"$ref": "#/components/parameters/accountIdOrNickname"},
278 %Schema{allOf: [BooleanLike], default: true},
279 "Mute notifications in addition to statuses? Defaults to `true`."
283 200 => Operation.response("Relationship", "application/json", AccountRelationship)
288 def unmute_operation do
292 operationId: "AccountController.unmute",
293 security: [%{"oAuth" => ["follow", "write:mutes"]}],
294 description: "Unmute the given account.",
295 parameters: [%Reference{"$ref": "#/components/parameters/accountIdOrNickname"}],
297 200 => Operation.response("Relationship", "application/json", AccountRelationship)
302 def block_operation do
306 operationId: "AccountController.block",
307 security: [%{"oAuth" => ["follow", "write:blocks"]}],
309 "Block the given account. Clients should filter statuses from this account if received (e.g. due to a boost in the Home timeline)",
310 parameters: [%Reference{"$ref": "#/components/parameters/accountIdOrNickname"}],
312 200 => Operation.response("Relationship", "application/json", AccountRelationship)
317 def unblock_operation do
321 operationId: "AccountController.unblock",
322 security: [%{"oAuth" => ["follow", "write:blocks"]}],
323 description: "Unblock the given account.",
324 parameters: [%Reference{"$ref": "#/components/parameters/accountIdOrNickname"}],
326 200 => Operation.response("Relationship", "application/json", AccountRelationship)
331 def follows_operation do
335 operationId: "AccountController.follows",
336 security: [%{"oAuth" => ["follow", "write:follows"]}],
337 requestBody: Helpers.request_body("Parameters", AccountFollowsRequest, required: true),
339 200 => Operation.response("Account", "application/json", Account)
344 def mutes_operation do
347 summary: "Muted accounts",
348 operationId: "AccountController.mutes",
349 description: "Accounts the user has muted.",
350 security: [%{"oAuth" => ["follow", "read:mutes"]}],
352 200 => Operation.response("Accounts", "application/json", AccountsResponse)
357 def blocks_operation do
360 summary: "Blocked users",
361 operationId: "AccountController.blocks",
362 description: "View your blocks. See also accounts/:id/{block,unblock}",
363 security: [%{"oAuth" => ["read:blocks"]}],
365 200 => Operation.response("Accounts", "application/json", AccountsResponse)
370 def endorsements_operation do
373 summary: "Endorsements",
374 operationId: "AccountController.endorsements",
375 description: "Not implemented",
376 security: [%{"oAuth" => ["read:accounts"]}],
378 200 => Operation.response("Empry array", "application/json", %Schema{type: :array})