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.Schemas.Account
  10   alias Pleroma.Web.ApiSpec.Schemas.ApiError
  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   import Pleroma.Web.ApiSpec.Helpers
  25
  26   @spec open_api_operation(atom) :: Operation.t()
  27   def open_api_operation(action) do
  28     operation = String.to_existing_atom("#{action}_operation")
  29     apply(__MODULE__, operation, [])
  30   end
  31
  32   @spec create_operation() :: Operation.t()
  33   def create_operation do
  34     %Operation{
  35       tags: ["accounts"],
  36       summary: "Register an account",
  37       description:
  38         "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.",
  39       operationId: "AccountController.create",
  40       requestBody: request_body("Parameters", AccountCreateRequest, required: true),
  41       responses: %{
  42         200 => Operation.response("Account", "application/json", AccountCreateResponse),
  43         400 => Operation.response("Error", "application/json", ApiError),
  44         403 => Operation.response("Error", "application/json", ApiError),
  45         429 => Operation.response("Error", "application/json", ApiError)
  46       }
  47     }
  48   end
  49
  50   def verify_credentials_operation do
  51     %Operation{
  52       tags: ["accounts"],
  53       description: "Test to make sure that the user token works.",
  54       summary: "Verify account credentials",
  55       operationId: "AccountController.verify_credentials",
  56       security: [%{"oAuth" => ["read:accounts"]}],
  57       responses: %{
  58         200 => Operation.response("Account", "application/json", Account)
  59       }
  60     }
  61   end
  62
  63   def update_credentials_operation do
  64     %Operation{
  65       tags: ["accounts"],
  66       summary: "Update account credentials",
  67       description: "Update the user's display and preferences.",
  68       operationId: "AccountController.update_credentials",
  69       security: [%{"oAuth" => ["write:accounts"]}],
  70       requestBody: request_body("Parameters", AccountUpdateCredentialsRequest, required: true),
  71       responses: %{
  72         200 => Operation.response("Account", "application/json", Account),
  73         403 => Operation.response("Error", "application/json", ApiError)
  74       }
  75     }
  76   end
  77
  78   def relationships_operation do
  79     %Operation{
  80       tags: ["accounts"],
  81       summary: "Check relationships to other accounts",
  82       operationId: "AccountController.relationships",
  83       description: "Find out whether a given account is followed, blocked, muted, etc.",
  84       security: [%{"oAuth" => ["read:follows"]}],
  85       parameters: [
  86         Operation.parameter(
  87           :id,
  88           :query,
  89           %Schema{
  90             oneOf: [%Schema{type: :array, items: %Schema{type: :string}}, %Schema{type: :string}]
  91           },
  92           "Account IDs",
  93           example: "123"
  94         )
  95       ],
  96       responses: %{
  97         200 => Operation.response("Account", "application/json", AccountRelationshipsResponse)
  98       }
  99     }
 100   end
 101
 102   def show_operation do
 103     %Operation{
 104       tags: ["accounts"],
 105       summary: "Account",
 106       operationId: "AccountController.show",
 107       description: "View information about a profile.",
 108       parameters: [%Reference{"$ref": "#/components/parameters/accountIdOrNickname"}],
 109       responses: %{
 110         200 => Operation.response("Account", "application/json", Account),
 111         404 => Operation.response("Error", "application/json", ApiError)
 112       }
 113     }
 114   end
 115
 116   def statuses_operation do
 117     %Operation{
 118       tags: ["accounts"],
 119       summary: "Statuses",
 120       operationId: "AccountController.statuses",
 121       description:
 122         "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)",
 123       parameters:
 124         [
 125           %Reference{"$ref": "#/components/parameters/accountIdOrNickname"},
 126           Operation.parameter(:pinned, :query, BooleanLike, "Include only pinned statuses"),
 127           Operation.parameter(:tagged, :query, :string, "With tag"),
 128           Operation.parameter(
 129             :only_media,
 130             :query,
 131             BooleanLike,
 132             "Include only statuses with media attached"
 133           ),
 134           Operation.parameter(
 135             :with_muted,
 136             :query,
 137             BooleanLike,
 138             "Include statuses from muted acccounts."
 139           ),
 140           Operation.parameter(:exclude_reblogs, :query, BooleanLike, "Exclude reblogs"),
 141           Operation.parameter(
 142             :exclude_visibilities,
 143             :query,
 144             %Schema{type: :array, items: VisibilityScope},
 145             "Exclude visibilities"
 146           )
 147         ] ++ pagination_params(),
 148       responses: %{
 149         200 => Operation.response("Statuses", "application/json", StatusesResponse),
 150         404 => Operation.response("Error", "application/json", ApiError)
 151       }
 152     }
 153   end
 154
 155   def followers_operation do
 156     %Operation{
 157       tags: ["accounts"],
 158       summary: "Followers",
 159       operationId: "AccountController.followers",
 160       security: [%{"oAuth" => ["read:accounts"]}],
 161       description:
 162         "Accounts which follow the given account, if network is not hidden by the account owner.",
 163       parameters:
 164         [%Reference{"$ref": "#/components/parameters/accountIdOrNickname"}] ++ pagination_params(),
 165       responses: %{
 166         200 => Operation.response("Accounts", "application/json", AccountsResponse)
 167       }
 168     }
 169   end
 170
 171   def following_operation do
 172     %Operation{
 173       tags: ["accounts"],
 174       summary: "Following",
 175       operationId: "AccountController.following",
 176       security: [%{"oAuth" => ["read:accounts"]}],
 177       description:
 178         "Accounts which the given account is following, if network is not hidden by the account owner.",
 179       parameters:
 180         [%Reference{"$ref": "#/components/parameters/accountIdOrNickname"}] ++ pagination_params(),
 181       responses: %{200 => Operation.response("Accounts", "application/json", AccountsResponse)}
 182     }
 183   end
 184
 185   def lists_operation do
 186     %Operation{
 187       tags: ["accounts"],
 188       summary: "Lists containing this account",
 189       operationId: "AccountController.lists",
 190       security: [%{"oAuth" => ["read:lists"]}],
 191       description: "User lists that you have added this account to.",
 192       parameters: [%Reference{"$ref": "#/components/parameters/accountIdOrNickname"}],
 193       responses: %{200 => Operation.response("Lists", "application/json", ListsResponse)}
 194     }
 195   end
 196
 197   def follow_operation do
 198     %Operation{
 199       tags: ["accounts"],
 200       summary: "Follow",
 201       operationId: "AccountController.follow",
 202       security: [%{"oAuth" => ["follow", "write:follows"]}],
 203       description: "Follow the given account",
 204       parameters: [
 205         %Reference{"$ref": "#/components/parameters/accountIdOrNickname"},
 206         Operation.parameter(
 207           :reblogs,
 208           :query,
 209           BooleanLike,
 210           "Receive this account's reblogs in home timeline? Defaults to true."
 211         )
 212       ],
 213       responses: %{
 214         200 => Operation.response("Relationship", "application/json", AccountRelationship),
 215         400 => Operation.response("Error", "application/json", ApiError),
 216         404 => Operation.response("Error", "application/json", ApiError)
 217       }
 218     }
 219   end
 220
 221   def unfollow_operation do
 222     %Operation{
 223       tags: ["accounts"],
 224       summary: "Unfollow",
 225       operationId: "AccountController.unfollow",
 226       security: [%{"oAuth" => ["follow", "write:follows"]}],
 227       description: "Unfollow the given account",
 228       parameters: [%Reference{"$ref": "#/components/parameters/accountIdOrNickname"}],
 229       responses: %{
 230         200 => Operation.response("Relationship", "application/json", AccountRelationship),
 231         400 => Operation.response("Error", "application/json", ApiError),
 232         404 => Operation.response("Error", "application/json", ApiError)
 233       }
 234     }
 235   end
 236
 237   def mute_operation do
 238     %Operation{
 239       tags: ["accounts"],
 240       summary: "Mute",
 241       operationId: "AccountController.mute",
 242       security: [%{"oAuth" => ["follow", "write:mutes"]}],
 243       requestBody: request_body("Parameters", AccountMuteRequest),
 244       description:
 245         "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).",
 246       parameters: [
 247         %Reference{"$ref": "#/components/parameters/accountIdOrNickname"},
 248         Operation.parameter(
 249           :notifications,
 250           :query,
 251           %Schema{allOf: [BooleanLike], default: true},
 252           "Mute notifications in addition to statuses? Defaults to `true`."
 253         )
 254       ],
 255       responses: %{
 256         200 => Operation.response("Relationship", "application/json", AccountRelationship)
 257       }
 258     }
 259   end
 260
 261   def unmute_operation do
 262     %Operation{
 263       tags: ["accounts"],
 264       summary: "Unmute",
 265       operationId: "AccountController.unmute",
 266       security: [%{"oAuth" => ["follow", "write:mutes"]}],
 267       description: "Unmute the given account.",
 268       parameters: [%Reference{"$ref": "#/components/parameters/accountIdOrNickname"}],
 269       responses: %{
 270         200 => Operation.response("Relationship", "application/json", AccountRelationship)
 271       }
 272     }
 273   end
 274
 275   def block_operation do
 276     %Operation{
 277       tags: ["accounts"],
 278       summary: "Block",
 279       operationId: "AccountController.block",
 280       security: [%{"oAuth" => ["follow", "write:blocks"]}],
 281       description:
 282         "Block the given account. Clients should filter statuses from this account if received (e.g. due to a boost in the Home timeline)",
 283       parameters: [%Reference{"$ref": "#/components/parameters/accountIdOrNickname"}],
 284       responses: %{
 285         200 => Operation.response("Relationship", "application/json", AccountRelationship)
 286       }
 287     }
 288   end
 289
 290   def unblock_operation do
 291     %Operation{
 292       tags: ["accounts"],
 293       summary: "Unblock",
 294       operationId: "AccountController.unblock",
 295       security: [%{"oAuth" => ["follow", "write:blocks"]}],
 296       description: "Unblock the given account.",
 297       parameters: [%Reference{"$ref": "#/components/parameters/accountIdOrNickname"}],
 298       responses: %{
 299         200 => Operation.response("Relationship", "application/json", AccountRelationship)
 300       }
 301     }
 302   end
 303
 304   def follows_operation do
 305     %Operation{
 306       tags: ["accounts"],
 307       summary: "Follows",
 308       operationId: "AccountController.follows",
 309       security: [%{"oAuth" => ["follow", "write:follows"]}],
 310       requestBody: request_body("Parameters", AccountFollowsRequest, required: true),
 311       responses: %{
 312         200 => Operation.response("Account", "application/json", AccountRelationship),
 313         400 => Operation.response("Error", "application/json", ApiError),
 314         404 => Operation.response("Error", "application/json", ApiError)
 315       }
 316     }
 317   end
 318
 319   def mutes_operation do
 320     %Operation{
 321       tags: ["accounts"],
 322       summary: "Muted accounts",
 323       operationId: "AccountController.mutes",
 324       description: "Accounts the user has muted.",
 325       security: [%{"oAuth" => ["follow", "read:mutes"]}],
 326       responses: %{
 327         200 => Operation.response("Accounts", "application/json", AccountsResponse)
 328       }
 329     }
 330   end
 331
 332   def blocks_operation do
 333     %Operation{
 334       tags: ["accounts"],
 335       summary: "Blocked users",
 336       operationId: "AccountController.blocks",
 337       description: "View your blocks. See also accounts/:id/{block,unblock}",
 338       security: [%{"oAuth" => ["read:blocks"]}],
 339       responses: %{
 340         200 => Operation.response("Accounts", "application/json", AccountsResponse)
 341       }
 342     }
 343   end
 344
 345   def endorsements_operation do
 346     %Operation{
 347       tags: ["accounts"],
 348       summary: "Endorsements",
 349       operationId: "AccountController.endorsements",
 350       description: "Not implemented",
 351       security: [%{"oAuth" => ["read:accounts"]}],
 352       responses: %{
 353         200 => Operation.response("Empry array", "application/json", %Schema{type: :array})
 354       }
 355     }
 356   end
 357
 358   def identity_proofs_operation do
 359     %Operation{
 360       tags: ["accounts"],
 361       summary: "Identity proofs",
 362       operationId: "AccountController.identity_proofs",
 363       description: "Not implemented",
 364       responses: %{
 365         200 => Operation.response("Empry array", "application/json", %Schema{type: :array})
 366       }
 367     }
 368   end
 369 end