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.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 @spec open_api_operation(atom) :: Operation.t()
24 def open_api_operation(action) do
25 operation = String.to_existing_atom("#{action}_operation")
26 apply(__MODULE__, operation, [])
29 @spec create_operation() :: Operation.t()
30 def create_operation do
33 summary: "Register an account",
35 "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.",
36 operationId: "AccountController.create",
37 requestBody: Helpers.request_body("Parameters", AccountCreateRequest, required: true),
39 200 => Operation.response("Account", "application/json", AccountCreateResponse)
44 def verify_credentials_operation do
47 description: "Test to make sure that the user token works.",
48 summary: "Verify account credentials",
49 operationId: "AccountController.verify_credentials",
50 security: [%{"oAuth" => ["read:accounts"]}],
52 200 => Operation.response("Account", "application/json", Account)
57 def update_credentials_operation do
60 summary: "Update account credentials",
61 description: "Update the user's display and preferences.",
62 operationId: "AccountController.update_credentials",
63 security: [%{"oAuth" => ["write:accounts"]}],
65 Helpers.request_body("Parameters", AccountUpdateCredentialsRequest, required: true),
67 200 => Operation.response("Account", "application/json", Account)
72 def relationships_operation do
75 summary: "Check relationships to other accounts",
76 operationId: "AccountController.relationships",
77 description: "Find out whether a given account is followed, blocked, muted, etc.",
78 security: [%{"oAuth" => ["read:follows"]}],
84 oneOf: [%Schema{type: :array, items: %Schema{type: :string}}, %Schema{type: :string}]
91 200 => Operation.response("Account", "application/json", AccountRelationshipsResponse)
100 operationId: "AccountController.show",
101 description: "View information about a profile.",
102 parameters: [%Reference{"$ref": "#/components/parameters/accountIdOrNickname"}],
104 200 => Operation.response("Account", "application/json", Account)
109 def statuses_operation do
113 operationId: "AccountController.statuses",
115 "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)",
117 %Reference{"$ref": "#/components/parameters/accountIdOrNickname"},
118 Operation.parameter(:pinned, :query, BooleanLike, "Pinned"),
119 Operation.parameter(:tagged, :query, :string, "With tag"),
120 Operation.parameter(:only_media, :query, BooleanLike, "Only meadia"),
121 Operation.parameter(:with_muted, :query, BooleanLike, "With muted"),
122 Operation.parameter(:exclude_reblogs, :query, BooleanLike, "Exclude reblobs"),
124 :exclude_visibilities,
126 %Schema{type: :array, items: VisibilityScope},
127 "Exclude visibilities"
129 Operation.parameter(:max_id, :query, :string, "Max ID"),
130 Operation.parameter(:min_id, :query, :string, "Mix ID"),
131 Operation.parameter(:since_id, :query, :string, "Since ID"),
135 %Schema{type: :integer, default: 20, maximum: 40},
140 200 => Operation.response("Statuses", "application/json", StatusesResponse)
145 def followers_operation do
148 summary: "Followers",
149 operationId: "AccountController.followers",
150 security: [%{"oAuth" => ["read:accounts"]}],
152 "Accounts which follow the given account, if network is not hidden by the account owner.",
154 %Reference{"$ref": "#/components/parameters/accountIdOrNickname"},
155 Operation.parameter(:max_id, :query, :string, "Max ID"),
156 Operation.parameter(:min_id, :query, :string, "Mix ID"),
157 Operation.parameter(:since_id, :query, :string, "Since ID"),
161 %Schema{type: :integer, default: 20, maximum: 40},
166 200 => Operation.response("Accounts", "application/json", AccountsResponse)
171 def following_operation do
174 summary: "Following",
175 operationId: "AccountController.following",
176 security: [%{"oAuth" => ["read:accounts"]}],
178 "Accounts which the given account is following, if network is not hidden by the account owner.",
180 %Reference{"$ref": "#/components/parameters/accountIdOrNickname"},
181 Operation.parameter(:max_id, :query, :string, "Max ID"),
182 Operation.parameter(:min_id, :query, :string, "Mix ID"),
183 Operation.parameter(:since_id, :query, :string, "Since ID"),
187 %Schema{type: :integer, default: 20, maximum: 40},
191 responses: %{200 => Operation.response("Accounts", "application/json", AccountsResponse)}
195 def lists_operation do
198 summary: "Lists containing this account",
199 operationId: "AccountController.lists",
200 security: [%{"oAuth" => ["read:lists"]}],
201 description: "User lists that you have added this account to.",
202 parameters: [%Reference{"$ref": "#/components/parameters/accountIdOrNickname"}],
203 responses: %{200 => Operation.response("Lists", "application/json", ListsResponse)}
207 def follow_operation do
211 operationId: "AccountController.follow",
212 security: [%{"oAuth" => ["follow", "write:follows"]}],
213 description: "Follow the given account",
215 %Reference{"$ref": "#/components/parameters/accountIdOrNickname"},
220 "Receive this account's reblogs in home timeline? Defaults to true."
224 200 => Operation.response("Relationship", "application/json", AccountRelationship)
229 def unfollow_operation do
233 operationId: "AccountController.unfollow",
234 security: [%{"oAuth" => ["follow", "write:follows"]}],
235 description: "Unfollow the given account",
236 parameters: [%Reference{"$ref": "#/components/parameters/accountIdOrNickname"}],
238 200 => Operation.response("Relationship", "application/json", AccountRelationship)
243 def mute_operation do
247 operationId: "AccountController.mute",
248 security: [%{"oAuth" => ["follow", "write:mutes"]}],
249 requestBody: Helpers.request_body("Parameters", AccountMuteRequest),
251 "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).",
253 %Reference{"$ref": "#/components/parameters/accountIdOrNickname"},
257 %Schema{allOf: [BooleanLike], default: true},
258 "Mute notifications in addition to statuses? Defaults to `true`."
262 200 => Operation.response("Relationship", "application/json", AccountRelationship)
267 def unmute_operation do
271 operationId: "AccountController.unmute",
272 security: [%{"oAuth" => ["follow", "write:mutes"]}],
273 description: "Unmute the given account.",
274 parameters: [%Reference{"$ref": "#/components/parameters/accountIdOrNickname"}],
276 200 => Operation.response("Relationship", "application/json", AccountRelationship)
281 def block_operation, do: :ok
282 def unblock_operation, do: :ok
283 def follows_operation, do: :ok
284 def mutes_operation, do: :ok
285 def blocks_operation, do: :ok
286 def endorsements_operation, do: :ok