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, "Pinned"),
120 Operation.parameter(:tagged, :query, :string, "With tag"),
121 Operation.parameter(:only_media, :query, BooleanLike, "Include only statuses with media attached"),
122 Operation.parameter(:with_muted, :query, BooleanLike, "Include statuses from muted acccounts."),
123 Operation.parameter(:exclude_reblogs, :query, BooleanLike, "Exclude reblogs"),
126 :exclude_visibilities,
128 %Schema{type: :array, items: VisibilityScope},
129 "Exclude visibilities"
131 Operation.parameter(:max_id, :query, :string, "Max ID"),
132 Operation.parameter(:min_id, :query, :string, "Mix ID"),
133 Operation.parameter(:since_id, :query, :string, "Since ID"),
137 %Schema{type: :integer, default: 20, maximum: 40},
142 200 => Operation.response("Statuses", "application/json", StatusesResponse)
147 def followers_operation do
150 summary: "Followers",
151 operationId: "AccountController.followers",
152 security: [%{"oAuth" => ["read:accounts"]}],
154 "Accounts which follow the given account, if network is not hidden by the account owner.",
156 %Reference{"$ref": "#/components/parameters/accountIdOrNickname"},
157 Operation.parameter(:max_id, :query, :string, "Max ID"),
158 Operation.parameter(:min_id, :query, :string, "Mix ID"),
159 Operation.parameter(:since_id, :query, :string, "Since ID"),
163 %Schema{type: :integer, default: 20, maximum: 40},
168 200 => Operation.response("Accounts", "application/json", AccountsResponse)
173 def following_operation do
176 summary: "Following",
177 operationId: "AccountController.following",
178 security: [%{"oAuth" => ["read:accounts"]}],
180 "Accounts which the given account is following, if network is not hidden by the account owner.",
182 %Reference{"$ref": "#/components/parameters/accountIdOrNickname"},
183 Operation.parameter(:max_id, :query, :string, "Max ID"),
184 Operation.parameter(:min_id, :query, :string, "Mix ID"),
185 Operation.parameter(:since_id, :query, :string, "Since ID"),
189 %Schema{type: :integer, default: 20, maximum: 40},
193 responses: %{200 => Operation.response("Accounts", "application/json", AccountsResponse)}
197 def lists_operation do
200 summary: "Lists containing this account",
201 operationId: "AccountController.lists",
202 security: [%{"oAuth" => ["read:lists"]}],
203 description: "User lists that you have added this account to.",
204 parameters: [%Reference{"$ref": "#/components/parameters/accountIdOrNickname"}],
205 responses: %{200 => Operation.response("Lists", "application/json", ListsResponse)}
209 def follow_operation do
213 operationId: "AccountController.follow",
214 security: [%{"oAuth" => ["follow", "write:follows"]}],
215 description: "Follow the given account",
217 %Reference{"$ref": "#/components/parameters/accountIdOrNickname"},
222 "Receive this account's reblogs in home timeline? Defaults to true."
226 200 => Operation.response("Relationship", "application/json", AccountRelationship)
231 def unfollow_operation do
235 operationId: "AccountController.unfollow",
236 security: [%{"oAuth" => ["follow", "write:follows"]}],
237 description: "Unfollow the given account",
238 parameters: [%Reference{"$ref": "#/components/parameters/accountIdOrNickname"}],
240 200 => Operation.response("Relationship", "application/json", AccountRelationship)
245 def mute_operation do
249 operationId: "AccountController.mute",
250 security: [%{"oAuth" => ["follow", "write:mutes"]}],
251 requestBody: Helpers.request_body("Parameters", AccountMuteRequest),
253 "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).",
255 %Reference{"$ref": "#/components/parameters/accountIdOrNickname"},
259 %Schema{allOf: [BooleanLike], default: true},
260 "Mute notifications in addition to statuses? Defaults to `true`."
264 200 => Operation.response("Relationship", "application/json", AccountRelationship)
269 def unmute_operation do
273 operationId: "AccountController.unmute",
274 security: [%{"oAuth" => ["follow", "write:mutes"]}],
275 description: "Unmute the given account.",
276 parameters: [%Reference{"$ref": "#/components/parameters/accountIdOrNickname"}],
278 200 => Operation.response("Relationship", "application/json", AccountRelationship)
283 def block_operation do
287 operationId: "AccountController.block",
288 security: [%{"oAuth" => ["follow", "write:blocks"]}],
290 "Block the given account. Clients should filter statuses from this account if received (e.g. due to a boost in the Home timeline)",
291 parameters: [%Reference{"$ref": "#/components/parameters/accountIdOrNickname"}],
293 200 => Operation.response("Relationship", "application/json", AccountRelationship)
298 def unblock_operation do
302 operationId: "AccountController.unblock",
303 security: [%{"oAuth" => ["follow", "write:blocks"]}],
304 description: "Unblock the given account.",
305 parameters: [%Reference{"$ref": "#/components/parameters/accountIdOrNickname"}],
307 200 => Operation.response("Relationship", "application/json", AccountRelationship)
312 def follows_operation do
316 operationId: "AccountController.follows",
317 security: [%{"oAuth" => ["follow", "write:follows"]}],
318 requestBody: Helpers.request_body("Parameters", AccountFollowsRequest, required: true),
320 200 => Operation.response("Account", "application/json", Account)
325 def mutes_operation do
328 summary: "Muted accounts",
329 operationId: "AccountController.mutes",
330 description: "Accounts the user has muted.",
331 security: [%{"oAuth" => ["follow", "read:mutes"]}],
333 200 => Operation.response("Accounts", "application/json", AccountsResponse)
338 def blocks_operation do
341 summary: "Blocked users",
342 operationId: "AccountController.blocks",
343 description: "View your blocks. See also accounts/:id/{block,unblock}",
344 security: [%{"oAuth" => ["read:blocks"]}],
346 200 => Operation.response("Accounts", "application/json", AccountsResponse)
351 def endorsements_operation do
354 summary: "Endorsements",
355 operationId: "AccountController.endorsements",
356 description: "Not implemented",
357 security: [%{"oAuth" => ["read:accounts"]}],
359 200 => Operation.response("Empry array", "application/json", %Schema{type: :array})