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