git.squeep.com Git - akkoma/blob - lib/pleroma/web/api_spec/operations/account_operation.ex

   1 # Pleroma: A lightweight social networking server
   2 # Copyright © 2017-2020 Pleroma Authors <https://pleroma.social/>
   3 # SPDX-License-Identifier: AGPL-3.0-only
   4
   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
  23
  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, [])
  28   end
  29
  30   @spec create_operation() :: Operation.t()
  31   def create_operation do
  32     %Operation{
  33       tags: ["accounts"],
  34       summary: "Register an account",
  35       description:
  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),
  39       responses: %{
  40         200 => Operation.response("Account", "application/json", AccountCreateResponse)
  41       }
  42     }
  43   end
  44
  45   def verify_credentials_operation do
  46     %Operation{
  47       tags: ["accounts"],
  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"]}],
  52       responses: %{
  53         200 => Operation.response("Account", "application/json", Account)
  54       }
  55     }
  56   end
  57
  58   def update_credentials_operation do
  59     %Operation{
  60       tags: ["accounts"],
  61       summary: "Update account credentials",
  62       description: "Update the user's display and preferences.",
  63       operationId: "AccountController.update_credentials",
  64       security: [%{"oAuth" => ["write:accounts"]}],
  65       requestBody:
  66         Helpers.request_body("Parameters", AccountUpdateCredentialsRequest, required: true),
  67       responses: %{
  68         200 => Operation.response("Account", "application/json", Account)
  69       }
  70     }
  71   end
  72
  73   def relationships_operation do
  74     %Operation{
  75       tags: ["accounts"],
  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"]}],
  80       parameters: [
  81         Operation.parameter(
  82           :id,
  83           :query,
  84           %Schema{
  85             oneOf: [%Schema{type: :array, items: %Schema{type: :string}}, %Schema{type: :string}]
  86           },
  87           "Account IDs",
  88           example: "123"
  89         )
  90       ],
  91       responses: %{
  92         200 => Operation.response("Account", "application/json", AccountRelationshipsResponse)
  93       }
  94     }
  95   end
  96
  97   def show_operation do
  98     %Operation{
  99       tags: ["accounts"],
 100       summary: "Account",
 101       operationId: "AccountController.show",
 102       description: "View information about a profile.",
 103       parameters: [%Reference{"$ref": "#/components/parameters/accountIdOrNickname"}],
 104       responses: %{
 105         200 => Operation.response("Account", "application/json", Account)
 106       }
 107     }
 108   end
 109
 110   def statuses_operation do
 111     %Operation{
 112       tags: ["accounts"],
 113       summary: "Statuses",
 114       operationId: "AccountController.statuses",
 115       description:
 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)",
 117       parameters: [
 118         %Reference{"$ref": "#/components/parameters/accountIdOrNickname"},
 119         Operation.parameter(:pinned, :query, BooleanLike, "Include only pinned statuses"),
 120         Operation.parameter(:tagged, :query, :string, "With tag"),
 121         Operation.parameter(
 122           :only_media,
 123           :query,
 124           BooleanLike,
 125           "Include only statuses with media attached"
 126         ),
 127         Operation.parameter(
 128           :with_muted,
 129           :query,
 130           BooleanLike,
 131           "Include statuses from muted acccounts."
 132         ),
 133         Operation.parameter(:exclude_reblogs, :query, BooleanLike, "Exclude reblogs"),
 134         Operation.parameter(
 135           :exclude_visibilities,
 136           :query,
 137           %Schema{type: :array, items: VisibilityScope},
 138           "Exclude visibilities"
 139         ),
 140         Operation.parameter(:max_id, :query, :string, "Return statuses older than this ID"),
 141         Operation.parameter(
 142           :min_id,
 143           :query,
 144           :string,
 145           "Return the oldest statuses newer than this ID"
 146         ),
 147         Operation.parameter(
 148           :since_id,
 149           :query,
 150           :string,
 151           "Return the newest statuses newer than this ID"
 152         ),
 153         Operation.parameter(
 154           :limit,
 155           :query,
 156           %Schema{type: :integer, default: 20, maximum: 40},
 157           "Limit"
 158         )
 159       ],
 160       responses: %{
 161         200 => Operation.response("Statuses", "application/json", StatusesResponse)
 162       }
 163     }
 164   end
 165
 166   def followers_operation do
 167     %Operation{
 168       tags: ["accounts"],
 169       summary: "Followers",
 170       operationId: "AccountController.followers",
 171       security: [%{"oAuth" => ["read:accounts"]}],
 172       description:
 173         "Accounts which follow the given account, if network is not hidden by the account owner.",
 174       parameters: [
 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"),
 179         Operation.parameter(
 180           :limit,
 181           :query,
 182           %Schema{type: :integer, default: 20, maximum: 40},
 183           "Limit"
 184         )
 185       ],
 186       responses: %{
 187         200 => Operation.response("Accounts", "application/json", AccountsResponse)
 188       }
 189     }
 190   end
 191
 192   def following_operation do
 193     %Operation{
 194       tags: ["accounts"],
 195       summary: "Following",
 196       operationId: "AccountController.following",
 197       security: [%{"oAuth" => ["read:accounts"]}],
 198       description:
 199         "Accounts which the given account is following, if network is not hidden by the account owner.",
 200       parameters: [
 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"),
 205         Operation.parameter(
 206           :limit,
 207           :query,
 208           %Schema{type: :integer, default: 20, maximum: 40},
 209           "Limit"
 210         )
 211       ],
 212       responses: %{200 => Operation.response("Accounts", "application/json", AccountsResponse)}
 213     }
 214   end
 215
 216   def lists_operation do
 217     %Operation{
 218       tags: ["accounts"],
 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)}
 225     }
 226   end
 227
 228   def follow_operation do
 229     %Operation{
 230       tags: ["accounts"],
 231       summary: "Follow",
 232       operationId: "AccountController.follow",
 233       security: [%{"oAuth" => ["follow", "write:follows"]}],
 234       description: "Follow the given account",
 235       parameters: [
 236         %Reference{"$ref": "#/components/parameters/accountIdOrNickname"},
 237         Operation.parameter(
 238           :reblogs,
 239           :query,
 240           BooleanLike,
 241           "Receive this account's reblogs in home timeline? Defaults to true."
 242         )
 243       ],
 244       responses: %{
 245         200 => Operation.response("Relationship", "application/json", AccountRelationship)
 246       }
 247     }
 248   end
 249
 250   def unfollow_operation do
 251     %Operation{
 252       tags: ["accounts"],
 253       summary: "Unfollow",
 254       operationId: "AccountController.unfollow",
 255       security: [%{"oAuth" => ["follow", "write:follows"]}],
 256       description: "Unfollow the given account",
 257       parameters: [%Reference{"$ref": "#/components/parameters/accountIdOrNickname"}],
 258       responses: %{
 259         200 => Operation.response("Relationship", "application/json", AccountRelationship)
 260       }
 261     }
 262   end
 263
 264   def mute_operation do
 265     %Operation{
 266       tags: ["accounts"],
 267       summary: "Mute",
 268       operationId: "AccountController.mute",
 269       security: [%{"oAuth" => ["follow", "write:mutes"]}],
 270       requestBody: Helpers.request_body("Parameters", AccountMuteRequest),
 271       description:
 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).",
 273       parameters: [
 274         %Reference{"$ref": "#/components/parameters/accountIdOrNickname"},
 275         Operation.parameter(
 276           :notifications,
 277           :query,
 278           %Schema{allOf: [BooleanLike], default: true},
 279           "Mute notifications in addition to statuses? Defaults to `true`."
 280         )
 281       ],
 282       responses: %{
 283         200 => Operation.response("Relationship", "application/json", AccountRelationship)
 284       }
 285     }
 286   end
 287
 288   def unmute_operation do
 289     %Operation{
 290       tags: ["accounts"],
 291       summary: "Unmute",
 292       operationId: "AccountController.unmute",
 293       security: [%{"oAuth" => ["follow", "write:mutes"]}],
 294       description: "Unmute the given account.",
 295       parameters: [%Reference{"$ref": "#/components/parameters/accountIdOrNickname"}],
 296       responses: %{
 297         200 => Operation.response("Relationship", "application/json", AccountRelationship)
 298       }
 299     }
 300   end
 301
 302   def block_operation do
 303     %Operation{
 304       tags: ["accounts"],
 305       summary: "Block",
 306       operationId: "AccountController.block",
 307       security: [%{"oAuth" => ["follow", "write:blocks"]}],
 308       description:
 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"}],
 311       responses: %{
 312         200 => Operation.response("Relationship", "application/json", AccountRelationship)
 313       }
 314     }
 315   end
 316
 317   def unblock_operation do
 318     %Operation{
 319       tags: ["accounts"],
 320       summary: "Unblock",
 321       operationId: "AccountController.unblock",
 322       security: [%{"oAuth" => ["follow", "write:blocks"]}],
 323       description: "Unblock the given account.",
 324       parameters: [%Reference{"$ref": "#/components/parameters/accountIdOrNickname"}],
 325       responses: %{
 326         200 => Operation.response("Relationship", "application/json", AccountRelationship)
 327       }
 328     }
 329   end
 330
 331   def follows_operation do
 332     %Operation{
 333       tags: ["accounts"],
 334       summary: "Follows",
 335       operationId: "AccountController.follows",
 336       security: [%{"oAuth" => ["follow", "write:follows"]}],
 337       requestBody: Helpers.request_body("Parameters", AccountFollowsRequest, required: true),
 338       responses: %{
 339         200 => Operation.response("Account", "application/json", Account)
 340       }
 341     }
 342   end
 343
 344   def mutes_operation do
 345     %Operation{
 346       tags: ["accounts"],
 347       summary: "Muted accounts",
 348       operationId: "AccountController.mutes",
 349       description: "Accounts the user has muted.",
 350       security: [%{"oAuth" => ["follow", "read:mutes"]}],
 351       responses: %{
 352         200 => Operation.response("Accounts", "application/json", AccountsResponse)
 353       }
 354     }
 355   end
 356
 357   def blocks_operation do
 358     %Operation{
 359       tags: ["accounts"],
 360       summary: "Blocked users",
 361       operationId: "AccountController.blocks",
 362       description: "View your blocks. See also accounts/:id/{block,unblock}",
 363       security: [%{"oAuth" => ["read:blocks"]}],
 364       responses: %{
 365         200 => Operation.response("Accounts", "application/json", AccountsResponse)
 366       }
 367     }
 368   end
 369
 370   def endorsements_operation do
 371     %Operation{
 372       tags: ["accounts"],
 373       summary: "Endorsements",
 374       operationId: "AccountController.endorsements",
 375       description: "Not implemented",
 376       security: [%{"oAuth" => ["read:accounts"]}],
 377       responses: %{
 378         200 => Operation.response("Empry array", "application/json", %Schema{type: :array})
 379       }
 380     }
 381   end
 382 end