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, "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"),
 124         Operation.parameter(
 125           :exclude_visibilities,
 126           :query,
 127           %Schema{type: :array, items: VisibilityScope},
 128           "Exclude visibilities"
 129         ),
 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"),
 133         Operation.parameter(
 134           :limit,
 135           :query,
 136           %Schema{type: :integer, default: 20, maximum: 40},
 137           "Limit"
 138         )
 139       ],
 140       responses: %{
 141         200 => Operation.response("Statuses", "application/json", StatusesResponse)
 142       }
 143     }
 144   end
 145
 146   def followers_operation do
 147     %Operation{
 148       tags: ["accounts"],
 149       summary: "Followers",
 150       operationId: "AccountController.followers",
 151       security: [%{"oAuth" => ["read:accounts"]}],
 152       description:
 153         "Accounts which follow the given account, if network is not hidden by the account owner.",
 154       parameters: [
 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"),
 159         Operation.parameter(
 160           :limit,
 161           :query,
 162           %Schema{type: :integer, default: 20, maximum: 40},
 163           "Limit"
 164         )
 165       ],
 166       responses: %{
 167         200 => Operation.response("Accounts", "application/json", AccountsResponse)
 168       }
 169     }
 170   end
 171
 172   def following_operation do
 173     %Operation{
 174       tags: ["accounts"],
 175       summary: "Following",
 176       operationId: "AccountController.following",
 177       security: [%{"oAuth" => ["read:accounts"]}],
 178       description:
 179         "Accounts which the given account is following, if network is not hidden by the account owner.",
 180       parameters: [
 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"),
 185         Operation.parameter(
 186           :limit,
 187           :query,
 188           %Schema{type: :integer, default: 20, maximum: 40},
 189           "Limit"
 190         )
 191       ],
 192       responses: %{200 => Operation.response("Accounts", "application/json", AccountsResponse)}
 193     }
 194   end
 195
 196   def lists_operation do
 197     %Operation{
 198       tags: ["accounts"],
 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)}
 205     }
 206   end
 207
 208   def follow_operation do
 209     %Operation{
 210       tags: ["accounts"],
 211       summary: "Follow",
 212       operationId: "AccountController.follow",
 213       security: [%{"oAuth" => ["follow", "write:follows"]}],
 214       description: "Follow the given account",
 215       parameters: [
 216         %Reference{"$ref": "#/components/parameters/accountIdOrNickname"},
 217         Operation.parameter(
 218           :reblogs,
 219           :query,
 220           BooleanLike,
 221           "Receive this account's reblogs in home timeline? Defaults to true."
 222         )
 223       ],
 224       responses: %{
 225         200 => Operation.response("Relationship", "application/json", AccountRelationship)
 226       }
 227     }
 228   end
 229
 230   def unfollow_operation do
 231     %Operation{
 232       tags: ["accounts"],
 233       summary: "Unfollow",
 234       operationId: "AccountController.unfollow",
 235       security: [%{"oAuth" => ["follow", "write:follows"]}],
 236       description: "Unfollow the given account",
 237       parameters: [%Reference{"$ref": "#/components/parameters/accountIdOrNickname"}],
 238       responses: %{
 239         200 => Operation.response("Relationship", "application/json", AccountRelationship)
 240       }
 241     }
 242   end
 243
 244   def mute_operation do
 245     %Operation{
 246       tags: ["accounts"],
 247       summary: "Mute",
 248       operationId: "AccountController.mute",
 249       security: [%{"oAuth" => ["follow", "write:mutes"]}],
 250       requestBody: Helpers.request_body("Parameters", AccountMuteRequest),
 251       description:
 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).",
 253       parameters: [
 254         %Reference{"$ref": "#/components/parameters/accountIdOrNickname"},
 255         Operation.parameter(
 256           :notifications,
 257           :query,
 258           %Schema{allOf: [BooleanLike], default: true},
 259           "Mute notifications in addition to statuses? Defaults to `true`."
 260         )
 261       ],
 262       responses: %{
 263         200 => Operation.response("Relationship", "application/json", AccountRelationship)
 264       }
 265     }
 266   end
 267
 268   def unmute_operation do
 269     %Operation{
 270       tags: ["accounts"],
 271       summary: "Unmute",
 272       operationId: "AccountController.unmute",
 273       security: [%{"oAuth" => ["follow", "write:mutes"]}],
 274       description: "Unmute the given account.",
 275       parameters: [%Reference{"$ref": "#/components/parameters/accountIdOrNickname"}],
 276       responses: %{
 277         200 => Operation.response("Relationship", "application/json", AccountRelationship)
 278       }
 279     }
 280   end
 281
 282   def block_operation do
 283     %Operation{
 284       tags: ["accounts"],
 285       summary: "Block",
 286       operationId: "AccountController.block",
 287       security: [%{"oAuth" => ["follow", "write:blocks"]}],
 288       description:
 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"}],
 291       responses: %{
 292         200 => Operation.response("Relationship", "application/json", AccountRelationship)
 293       }
 294     }
 295   end
 296
 297   def unblock_operation do
 298     %Operation{
 299       tags: ["accounts"],
 300       summary: "Unblock",
 301       operationId: "AccountController.unblock",
 302       security: [%{"oAuth" => ["follow", "write:blocks"]}],
 303       description: "Unblock the given account.",
 304       parameters: [%Reference{"$ref": "#/components/parameters/accountIdOrNickname"}],
 305       responses: %{
 306         200 => Operation.response("Relationship", "application/json", AccountRelationship)
 307       }
 308     }
 309   end
 310
 311   def follows_operation do
 312     %Operation{
 313       tags: ["accounts"],
 314       summary: "Follows",
 315       operationId: "AccountController.follows",
 316       security: [%{"oAuth" => ["follow", "write:follows"]}],
 317       requestBody: Helpers.request_body("Parameters", AccountFollowsRequest, required: true),
 318       responses: %{
 319         200 => Operation.response("Account", "application/json", Account)
 320       }
 321     }
 322   end
 323
 324   def mutes_operation do
 325     %Operation{
 326       tags: ["accounts"],
 327       summary: "Muted accounts",
 328       operationId: "AccountController.mutes",
 329       description: "Accounts the user has muted.",
 330       security: [%{"oAuth" => ["follow", "read:mutes"]}],
 331       responses: %{
 332         200 => Operation.response("Accounts", "application/json", AccountsResponse)
 333       }
 334     }
 335   end
 336
 337   def blocks_operation do
 338     %Operation{
 339       tags: ["accounts"],
 340       summary: "Blocked users",
 341       operationId: "AccountController.blocks",
 342       description: "View your blocks. See also accounts/:id/{block,unblock}",
 343       security: [%{"oAuth" => ["read:blocks"]}],
 344       responses: %{
 345         200 => Operation.response("Accounts", "application/json", AccountsResponse)
 346       }
 347     }
 348   end
 349
 350   def endorsements_operation do
 351     %Operation{
 352       tags: ["accounts"],
 353       summary: "Endorsements",
 354       operationId: "AccountController.endorsements",
 355       description: "Not implemented",
 356       security: [%{"oAuth" => ["read:accounts"]}],
 357       responses: %{
 358         200 => Operation.response("Empry array", "application/json", %Schema{type: :array})
 359       }
 360     }
 361   end
 362 end