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, "Only meadia"),
122 Operation.parameter(:with_muted, :query, BooleanLike, "With muted"),
123 Operation.parameter(:exclude_reblogs, :query, BooleanLike, "Exclude reblobs"),
125 :exclude_visibilities,
127 %Schema{type: :array, items: VisibilityScope},
128 "Exclude visibilities"
130 Operation.parameter(:max_id, :query, :string, "Max ID"),
131 Operation.parameter(:min_id, :query, :string, "Mix ID"),
132 Operation.parameter(:since_id, :query, :string, "Since ID"),
136 %Schema{type: :integer, default: 20, maximum: 40},
141 200 => Operation.response("Statuses", "application/json", StatusesResponse)
146 def followers_operation do
149 summary: "Followers",
150 operationId: "AccountController.followers",
151 security: [%{"oAuth" => ["read:accounts"]}],
153 "Accounts which follow the given account, if network is not hidden by the account owner.",
155 %Reference{"$ref": "#/components/parameters/accountIdOrNickname"},
156 Operation.parameter(:max_id, :query, :string, "Max ID"),
157 Operation.parameter(:min_id, :query, :string, "Mix ID"),
158 Operation.parameter(:since_id, :query, :string, "Since ID"),
162 %Schema{type: :integer, default: 20, maximum: 40},
167 200 => Operation.response("Accounts", "application/json", AccountsResponse)
172 def following_operation do
175 summary: "Following",
176 operationId: "AccountController.following",
177 security: [%{"oAuth" => ["read:accounts"]}],
179 "Accounts which the given account is following, if network is not hidden by the account owner.",
181 %Reference{"$ref": "#/components/parameters/accountIdOrNickname"},
182 Operation.parameter(:max_id, :query, :string, "Max ID"),
183 Operation.parameter(:min_id, :query, :string, "Mix ID"),
184 Operation.parameter(:since_id, :query, :string, "Since ID"),
188 %Schema{type: :integer, default: 20, maximum: 40},
192 responses: %{200 => Operation.response("Accounts", "application/json", AccountsResponse)}
196 def lists_operation do
199 summary: "Lists containing this account",
200 operationId: "AccountController.lists",
201 security: [%{"oAuth" => ["read:lists"]}],
202 description: "User lists that you have added this account to.",
203 parameters: [%Reference{"$ref": "#/components/parameters/accountIdOrNickname"}],
204 responses: %{200 => Operation.response("Lists", "application/json", ListsResponse)}
208 def follow_operation do
212 operationId: "AccountController.follow",
213 security: [%{"oAuth" => ["follow", "write:follows"]}],
214 description: "Follow the given account",
216 %Reference{"$ref": "#/components/parameters/accountIdOrNickname"},
221 "Receive this account's reblogs in home timeline? Defaults to true."
225 200 => Operation.response("Relationship", "application/json", AccountRelationship)
230 def unfollow_operation do
234 operationId: "AccountController.unfollow",
235 security: [%{"oAuth" => ["follow", "write:follows"]}],
236 description: "Unfollow the given account",
237 parameters: [%Reference{"$ref": "#/components/parameters/accountIdOrNickname"}],
239 200 => Operation.response("Relationship", "application/json", AccountRelationship)
244 def mute_operation do
248 operationId: "AccountController.mute",
249 security: [%{"oAuth" => ["follow", "write:mutes"]}],
250 requestBody: Helpers.request_body("Parameters", AccountMuteRequest),
252 "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).",
254 %Reference{"$ref": "#/components/parameters/accountIdOrNickname"},
258 %Schema{allOf: [BooleanLike], default: true},
259 "Mute notifications in addition to statuses? Defaults to `true`."
263 200 => Operation.response("Relationship", "application/json", AccountRelationship)
268 def unmute_operation do
272 operationId: "AccountController.unmute",
273 security: [%{"oAuth" => ["follow", "write:mutes"]}],
274 description: "Unmute the given account.",
275 parameters: [%Reference{"$ref": "#/components/parameters/accountIdOrNickname"}],
277 200 => Operation.response("Relationship", "application/json", AccountRelationship)
282 def block_operation do
286 operationId: "AccountController.block",
287 security: [%{"oAuth" => ["follow", "write:blocks"]}],
289 "Block the given account. Clients should filter statuses from this account if received (e.g. due to a boost in the Home timeline)",
290 parameters: [%Reference{"$ref": "#/components/parameters/accountIdOrNickname"}],
292 200 => Operation.response("Relationship", "application/json", AccountRelationship)
297 def unblock_operation do
301 operationId: "AccountController.unblock",
302 security: [%{"oAuth" => ["follow", "write:blocks"]}],
303 description: "Unblock the given account.",
304 parameters: [%Reference{"$ref": "#/components/parameters/accountIdOrNickname"}],
306 200 => Operation.response("Relationship", "application/json", AccountRelationship)
311 def follows_operation do
315 operationId: "AccountController.follows",
316 security: [%{"oAuth" => ["follow", "write:follows"]}],
317 requestBody: Helpers.request_body("Parameters", AccountFollowsRequest, required: true),
319 200 => Operation.response("Account", "application/json", Account)
324 def mutes_operation, do: :ok
325 def blocks_operation, do: :ok
326 def endorsements_operation, do: :ok