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.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
  22
  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, [])
  27   end
  28
  29   @spec create_operation() :: Operation.t()
  30   def create_operation do
  31     %Operation{
  32       tags: ["accounts"],
  33       summary: "Register an account",
  34       description:
  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),
  38       responses: %{
  39         200 => Operation.response("Account", "application/json", AccountCreateResponse)
  40       }
  41     }
  42   end
  43
  44   def verify_credentials_operation do
  45     %Operation{
  46       tags: ["accounts"],
  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"]}],
  51       responses: %{
  52         200 => Operation.response("Account", "application/json", Account)
  53       }
  54     }
  55   end
  56
  57   def update_credentials_operation do
  58     %Operation{
  59       tags: ["accounts"],
  60       summary: "Update account credentials",
  61       description: "Update the user's display and preferences.",
  62       operationId: "AccountController.update_credentials",
  63       security: [%{"oAuth" => ["write:accounts"]}],
  64       requestBody:
  65         Helpers.request_body("Parameters", AccountUpdateCredentialsRequest, required: true),
  66       responses: %{
  67         200 => Operation.response("Account", "application/json", Account)
  68       }
  69     }
  70   end
  71
  72   def relationships_operation do
  73     %Operation{
  74       tags: ["accounts"],
  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"]}],
  79       parameters: [
  80         Operation.parameter(
  81           :id,
  82           :query,
  83           %Schema{
  84             oneOf: [%Schema{type: :array, items: %Schema{type: :string}}, %Schema{type: :string}]
  85           },
  86           "Account IDs",
  87           example: "123"
  88         )
  89       ],
  90       responses: %{
  91         200 => Operation.response("Account", "application/json", AccountRelationshipsResponse)
  92       }
  93     }
  94   end
  95
  96   def show_operation do
  97     %Operation{
  98       tags: ["accounts"],
  99       summary: "Account",
 100       operationId: "AccountController.show",
 101       description: "View information about a profile.",
 102       parameters: [%Reference{"$ref": "#/components/parameters/accountIdOrNickname"}],
 103       responses: %{
 104         200 => Operation.response("Account", "application/json", Account)
 105       }
 106     }
 107   end
 108
 109   def statuses_operation do
 110     %Operation{
 111       tags: ["accounts"],
 112       summary: "Statuses",
 113       operationId: "AccountController.statuses",
 114       description:
 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)",
 116       parameters: [
 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"),
 123         Operation.parameter(
 124           :exclude_visibilities,
 125           :query,
 126           %Schema{type: :array, items: VisibilityScope},
 127           "Exclude visibilities"
 128         ),
 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"),
 132         Operation.parameter(
 133           :limit,
 134           :query,
 135           %Schema{type: :integer, default: 20, maximum: 40},
 136           "Limit"
 137         )
 138       ],
 139       responses: %{
 140         200 => Operation.response("Statuses", "application/json", StatusesResponse)
 141       }
 142     }
 143   end
 144
 145   def followers_operation do
 146     %Operation{
 147       tags: ["accounts"],
 148       summary: "Followers",
 149       operationId: "AccountController.followers",
 150       security: [%{"oAuth" => ["read:accounts"]}],
 151       description:
 152         "Accounts which follow the given account, if network is not hidden by the account owner.",
 153       parameters: [
 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"),
 158         Operation.parameter(
 159           :limit,
 160           :query,
 161           %Schema{type: :integer, default: 20, maximum: 40},
 162           "Limit"
 163         )
 164       ],
 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"},
 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"),
 184         Operation.parameter(
 185           :limit,
 186           :query,
 187           %Schema{type: :integer, default: 20, maximum: 40},
 188           "Limit"
 189         )
 190       ],
 191       responses: %{200 => Operation.response("Accounts", "application/json", AccountsResponse)}
 192     }
 193   end
 194
 195   def lists_operation do
 196     %Operation{
 197       tags: ["accounts"],
 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)}
 204     }
 205   end
 206
 207   def follow_operation do
 208     %Operation{
 209       tags: ["accounts"],
 210       summary: "Follow",
 211       operationId: "AccountController.follow",
 212       security: [%{"oAuth" => ["follow", "write:follows"]}],
 213       description: "Follow the given account",
 214       parameters: [
 215         %Reference{"$ref": "#/components/parameters/accountIdOrNickname"},
 216         Operation.parameter(
 217           :reblogs,
 218           :query,
 219           BooleanLike,
 220           "Receive this account's reblogs in home timeline? Defaults to true."
 221         )
 222       ],
 223       responses: %{
 224         200 => Operation.response("Relationship", "application/json", AccountRelationship)
 225       }
 226     }
 227   end
 228
 229   def unfollow_operation do
 230     %Operation{
 231       tags: ["accounts"],
 232       summary: "Unfollow",
 233       operationId: "AccountController.unfollow",
 234       security: [%{"oAuth" => ["follow", "write:follows"]}],
 235       description: "Unfollow the given account",
 236       parameters: [%Reference{"$ref": "#/components/parameters/accountIdOrNickname"}],
 237       responses: %{
 238         200 => Operation.response("Relationship", "application/json", AccountRelationship)
 239       }
 240     }
 241   end
 242
 243   def mute_operation do
 244     %Operation{
 245       tags: ["accounts"],
 246       summary: "Mute",
 247       operationId: "AccountController.mute",
 248       security: [%{"oAuth" => ["follow", "write:mutes"]}],
 249       requestBody: Helpers.request_body("Parameters", AccountMuteRequest),
 250       description:
 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).",
 252       parameters: [
 253         %Reference{"$ref": "#/components/parameters/accountIdOrNickname"},
 254         Operation.parameter(
 255           :notifications,
 256           :query,
 257           %Schema{allOf: [BooleanLike], default: true},
 258           "Mute notifications in addition to statuses? Defaults to `true`."
 259         )
 260       ],
 261       responses: %{
 262         200 => Operation.response("Relationship", "application/json", AccountRelationship)
 263       }
 264     }
 265   end
 266
 267   def unmute_operation do
 268     %Operation{
 269       tags: ["accounts"],
 270       summary: "Unmute",
 271       operationId: "AccountController.unmute",
 272       security: [%{"oAuth" => ["follow", "write:mutes"]}],
 273       description: "Unmute the given account.",
 274       parameters: [%Reference{"$ref": "#/components/parameters/accountIdOrNickname"}],
 275       responses: %{
 276         200 => Operation.response("Relationship", "application/json", AccountRelationship)
 277       }
 278     }
 279   end
 280
 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
 287 end