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.AccountCreateRequest
11 alias Pleroma.Web.ApiSpec.Schemas.AccountCreateResponse
12 alias Pleroma.Web.ApiSpec.Schemas.AccountFollowsRequest
13 alias Pleroma.Web.ApiSpec.Schemas.AccountMuteRequest
14 alias Pleroma.Web.ApiSpec.Schemas.AccountRelationship
15 alias Pleroma.Web.ApiSpec.Schemas.AccountRelationshipsResponse
16 alias Pleroma.Web.ApiSpec.Schemas.AccountsResponse
17 alias Pleroma.Web.ApiSpec.Schemas.AccountUpdateCredentialsRequest
18 alias Pleroma.Web.ApiSpec.Schemas.BooleanLike
19 alias Pleroma.Web.ApiSpec.Schemas.ListsResponse
20 alias Pleroma.Web.ApiSpec.Schemas.StatusesResponse
21 alias Pleroma.Web.ApiSpec.Schemas.VisibilityScope
23 import Pleroma.Web.ApiSpec.Helpers
25 @spec open_api_operation(atom) :: Operation.t()
26 def open_api_operation(action) do
27 operation = String.to_existing_atom("#{action}_operation")
28 apply(__MODULE__, operation, [])
31 @spec create_operation() :: Operation.t()
32 def create_operation do
35 summary: "Register an account",
37 "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.",
38 operationId: "AccountController.create",
39 requestBody: request_body("Parameters", AccountCreateRequest, required: true),
41 200 => Operation.response("Account", "application/json", AccountCreateResponse)
46 def verify_credentials_operation do
49 description: "Test to make sure that the user token works.",
50 summary: "Verify account credentials",
51 operationId: "AccountController.verify_credentials",
52 security: [%{"oAuth" => ["read:accounts"]}],
54 200 => Operation.response("Account", "application/json", Account)
59 def update_credentials_operation do
62 summary: "Update account credentials",
63 description: "Update the user's display and preferences.",
64 operationId: "AccountController.update_credentials",
65 security: [%{"oAuth" => ["write:accounts"]}],
66 requestBody: 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)",
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"),
136 :exclude_visibilities,
138 %Schema{type: :array, items: VisibilityScope},
139 "Exclude visibilities"
141 ] ++ pagination_params(),
143 200 => Operation.response("Statuses", "application/json", StatusesResponse)
148 def followers_operation do
151 summary: "Followers",
152 operationId: "AccountController.followers",
153 security: [%{"oAuth" => ["read:accounts"]}],
155 "Accounts which follow the given account, if network is not hidden by the account owner.",
157 [%Reference{"$ref": "#/components/parameters/accountIdOrNickname"}] ++ pagination_params(),
159 200 => Operation.response("Accounts", "application/json", AccountsResponse)
164 def following_operation do
167 summary: "Following",
168 operationId: "AccountController.following",
169 security: [%{"oAuth" => ["read:accounts"]}],
171 "Accounts which the given account is following, if network is not hidden by the account owner.",
173 [%Reference{"$ref": "#/components/parameters/accountIdOrNickname"}] ++ pagination_params(),
174 responses: %{200 => Operation.response("Accounts", "application/json", AccountsResponse)}
178 def lists_operation do
181 summary: "Lists containing this account",
182 operationId: "AccountController.lists",
183 security: [%{"oAuth" => ["read:lists"]}],
184 description: "User lists that you have added this account to.",
185 parameters: [%Reference{"$ref": "#/components/parameters/accountIdOrNickname"}],
186 responses: %{200 => Operation.response("Lists", "application/json", ListsResponse)}
190 def follow_operation do
194 operationId: "AccountController.follow",
195 security: [%{"oAuth" => ["follow", "write:follows"]}],
196 description: "Follow the given account",
198 %Reference{"$ref": "#/components/parameters/accountIdOrNickname"},
203 "Receive this account's reblogs in home timeline? Defaults to true."
207 200 => Operation.response("Relationship", "application/json", AccountRelationship)
212 def unfollow_operation do
216 operationId: "AccountController.unfollow",
217 security: [%{"oAuth" => ["follow", "write:follows"]}],
218 description: "Unfollow the given account",
219 parameters: [%Reference{"$ref": "#/components/parameters/accountIdOrNickname"}],
221 200 => Operation.response("Relationship", "application/json", AccountRelationship)
226 def mute_operation do
230 operationId: "AccountController.mute",
231 security: [%{"oAuth" => ["follow", "write:mutes"]}],
232 requestBody: request_body("Parameters", AccountMuteRequest),
234 "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).",
236 %Reference{"$ref": "#/components/parameters/accountIdOrNickname"},
240 %Schema{allOf: [BooleanLike], default: true},
241 "Mute notifications in addition to statuses? Defaults to `true`."
245 200 => Operation.response("Relationship", "application/json", AccountRelationship)
250 def unmute_operation do
254 operationId: "AccountController.unmute",
255 security: [%{"oAuth" => ["follow", "write:mutes"]}],
256 description: "Unmute the given account.",
257 parameters: [%Reference{"$ref": "#/components/parameters/accountIdOrNickname"}],
259 200 => Operation.response("Relationship", "application/json", AccountRelationship)
264 def block_operation do
268 operationId: "AccountController.block",
269 security: [%{"oAuth" => ["follow", "write:blocks"]}],
271 "Block the given account. Clients should filter statuses from this account if received (e.g. due to a boost in the Home timeline)",
272 parameters: [%Reference{"$ref": "#/components/parameters/accountIdOrNickname"}],
274 200 => Operation.response("Relationship", "application/json", AccountRelationship)
279 def unblock_operation do
283 operationId: "AccountController.unblock",
284 security: [%{"oAuth" => ["follow", "write:blocks"]}],
285 description: "Unblock the given account.",
286 parameters: [%Reference{"$ref": "#/components/parameters/accountIdOrNickname"}],
288 200 => Operation.response("Relationship", "application/json", AccountRelationship)
293 def follows_operation do
297 operationId: "AccountController.follows",
298 security: [%{"oAuth" => ["follow", "write:follows"]}],
299 requestBody: request_body("Parameters", AccountFollowsRequest, required: true),
301 200 => Operation.response("Account", "application/json", Account)
306 def mutes_operation do
309 summary: "Muted accounts",
310 operationId: "AccountController.mutes",
311 description: "Accounts the user has muted.",
312 security: [%{"oAuth" => ["follow", "read:mutes"]}],
314 200 => Operation.response("Accounts", "application/json", AccountsResponse)
319 def blocks_operation do
322 summary: "Blocked users",
323 operationId: "AccountController.blocks",
324 description: "View your blocks. See also accounts/:id/{block,unblock}",
325 security: [%{"oAuth" => ["read:blocks"]}],
327 200 => Operation.response("Accounts", "application/json", AccountsResponse)
332 def endorsements_operation do
335 summary: "Endorsements",
336 operationId: "AccountController.endorsements",
337 description: "Not implemented",
338 security: [%{"oAuth" => ["read:accounts"]}],
340 200 => Operation.response("Empry array", "application/json", %Schema{type: :array})