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.AccountRelationship
  14   alias Pleroma.Web.ApiSpec.Schemas.AccountRelationshipsResponse
  15   alias Pleroma.Web.ApiSpec.Schemas.AccountsResponse
  16   alias Pleroma.Web.ApiSpec.Schemas.AccountUpdateCredentialsRequest
  17   alias Pleroma.Web.ApiSpec.Schemas.BooleanLike
  18   alias Pleroma.Web.ApiSpec.Schemas.ListsResponse
  19   alias Pleroma.Web.ApiSpec.Schemas.StatusesResponse
  20   alias Pleroma.Web.ApiSpec.Schemas.VisibilityScope
  21
  22   @spec open_api_operation(atom) :: Operation.t()
  23   def open_api_operation(action) do
  24     operation = String.to_existing_atom("#{action}_operation")
  25     apply(__MODULE__, operation, [])
  26   end
  27
  28   @spec create_operation() :: Operation.t()
  29   def create_operation do
  30     %Operation{
  31       tags: ["accounts"],
  32       summary: "Register an account",
  33       description:
  34         "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.",
  35       operationId: "AccountController.create",
  36       requestBody: Helpers.request_body("Parameters", AccountCreateRequest, required: true),
  37       responses: %{
  38         200 => Operation.response("Account", "application/json", AccountCreateResponse)
  39       }
  40     }
  41   end
  42
  43   def verify_credentials_operation do
  44     %Operation{
  45       tags: ["accounts"],
  46       description: "Test to make sure that the user token works.",
  47       summary: "Verify account credentials",
  48       operationId: "AccountController.verify_credentials",
  49       security: [%{"oAuth" => ["read:accounts"]}],
  50       responses: %{
  51         200 => Operation.response("Account", "application/json", Account)
  52       }
  53     }
  54   end
  55
  56   def update_credentials_operation do
  57     %Operation{
  58       tags: ["accounts"],
  59       summary: "Update account credentials",
  60       description: "Update the user's display and preferences.",
  61       operationId: "AccountController.update_credentials",
  62       security: [%{"oAuth" => ["write:accounts"]}],
  63       requestBody:
  64         Helpers.request_body("Parameters", AccountUpdateCredentialsRequest, required: true),
  65       responses: %{
  66         200 => Operation.response("Account", "application/json", Account)
  67       }
  68     }
  69   end
  70
  71   def relationships_operation do
  72     %Operation{
  73       tags: ["accounts"],
  74       summary: "Check relationships to other accounts",
  75       operationId: "AccountController.relationships",
  76       description: "Find out whether a given account is followed, blocked, muted, etc.",
  77       security: [%{"oAuth" => ["read:follows"]}],
  78       parameters: [
  79         Operation.parameter(
  80           :id,
  81           :query,
  82           %Schema{
  83             oneOf: [%Schema{type: :array, items: %Schema{type: :string}}, %Schema{type: :string}]
  84           },
  85           "Account IDs",
  86           example: "123"
  87         )
  88       ],
  89       responses: %{
  90         200 => Operation.response("Account", "application/json", AccountRelationshipsResponse)
  91       }
  92     }
  93   end
  94
  95   def show_operation do
  96     %Operation{
  97       tags: ["accounts"],
  98       summary: "Account",
  99       operationId: "AccountController.show",
 100       description: "View information about a profile.",
 101       parameters: [%Reference{"$ref": "#/components/parameters/accountIdOrNickname"}],
 102       responses: %{
 103         200 => Operation.response("Account", "application/json", Account)
 104       }
 105     }
 106   end
 107
 108   def statuses_operation do
 109     %Operation{
 110       tags: ["accounts"],
 111       summary: "Statuses",
 112       operationId: "AccountController.statuses",
 113       description:
 114         "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)",
 115       parameters: [
 116         %Reference{"$ref": "#/components/parameters/accountIdOrNickname"},
 117         Operation.parameter(:pinned, :query, BooleanLike, "Pinned"),
 118         Operation.parameter(:tagged, :query, :string, "With tag"),
 119         Operation.parameter(:only_media, :query, BooleanLike, "Only meadia"),
 120         Operation.parameter(:with_muted, :query, BooleanLike, "With muted"),
 121         Operation.parameter(:exclude_reblogs, :query, BooleanLike, "Exclude reblobs"),
 122         Operation.parameter(
 123           :exclude_visibilities,
 124           :query,
 125           %Schema{type: :array, items: VisibilityScope},
 126           "Exclude visibilities"
 127         ),
 128         Operation.parameter(:max_id, :query, :string, "Max ID"),
 129         Operation.parameter(:min_id, :query, :string, "Mix ID"),
 130         Operation.parameter(:since_id, :query, :string, "Since ID"),
 131         Operation.parameter(
 132           :limit,
 133           :query,
 134           %Schema{type: :integer, default: 20, maximum: 40},
 135           "Limit"
 136         )
 137       ],
 138       responses: %{
 139         200 => Operation.response("Statuses", "application/json", StatusesResponse)
 140       }
 141     }
 142   end
 143
 144   def followers_operation do
 145     %Operation{
 146       tags: ["accounts"],
 147       summary: "Followers",
 148       operationId: "AccountController.followers",
 149       security: [%{"oAuth" => ["read:accounts"]}],
 150       description:
 151         "Accounts which follow the given account, if network is not hidden by the account owner.",
 152       parameters: [
 153         %Reference{"$ref": "#/components/parameters/accountIdOrNickname"},
 154         Operation.parameter(:max_id, :query, :string, "Max ID"),
 155         Operation.parameter(:min_id, :query, :string, "Mix ID"),
 156         Operation.parameter(:since_id, :query, :string, "Since ID"),
 157         Operation.parameter(
 158           :limit,
 159           :query,
 160           %Schema{type: :integer, default: 20, maximum: 40},
 161           "Limit"
 162         )
 163       ],
 164       responses: %{
 165         200 => Operation.response("Accounts", "application/json", AccountsResponse)
 166       }
 167     }
 168   end
 169
 170   def following_operation do
 171     %Operation{
 172       tags: ["accounts"],
 173       summary: "Following",
 174       operationId: "AccountController.following",
 175       security: [%{"oAuth" => ["read:accounts"]}],
 176       description:
 177         "Accounts which the given account is following, if network is not hidden by the account owner.",
 178       parameters: [
 179         %Reference{"$ref": "#/components/parameters/accountIdOrNickname"},
 180         Operation.parameter(:max_id, :query, :string, "Max ID"),
 181         Operation.parameter(:min_id, :query, :string, "Mix ID"),
 182         Operation.parameter(:since_id, :query, :string, "Since ID"),
 183         Operation.parameter(
 184           :limit,
 185           :query,
 186           %Schema{type: :integer, default: 20, maximum: 40},
 187           "Limit"
 188         )
 189       ],
 190       responses: %{200 => Operation.response("Accounts", "application/json", AccountsResponse)}
 191     }
 192   end
 193
 194   def lists_operation do
 195     %Operation{
 196       tags: ["accounts"],
 197       summary: "Lists containing this account",
 198       operationId: "AccountController.lists",
 199       security: [%{"oAuth" => ["read:lists"]}],
 200       description: "User lists that you have added this account to.",
 201       parameters: [%Reference{"$ref": "#/components/parameters/accountIdOrNickname"}],
 202       responses: %{200 => Operation.response("Lists", "application/json", ListsResponse)}
 203     }
 204   end
 205
 206   def follow_operation do
 207     %Operation{
 208       tags: ["accounts"],
 209       summary: "Follow",
 210       operationId: "AccountController.follow",
 211       security: [%{"oAuth" => ["follow", "write:follows"]}],
 212       description: "Follow the given account",
 213       parameters: [
 214         %Reference{"$ref": "#/components/parameters/accountIdOrNickname"},
 215         Operation.parameter(
 216           :reblogs,
 217           :query,
 218           BooleanLike,
 219           "Receive this account's reblogs in home timeline? Defaults to true."
 220         )
 221       ],
 222       responses: %{
 223         200 => Operation.response("Relationship", "application/json", AccountRelationship)
 224       }
 225     }
 226   end
 227
 228   def unfollow_operation do
 229     %Operation{
 230       tags: ["accounts"],
 231       summary: "Unfollow",
 232       operationId: "AccountController.unfollow",
 233       security: [%{"oAuth" => ["follow", "write:follows"]}],
 234       description: "Unfollow the given account",
 235       parameters: [%Reference{"$ref": "#/components/parameters/accountIdOrNickname"}],
 236       responses: %{
 237         200 => Operation.response("Relationship", "application/json", AccountRelationship)
 238       }
 239     }
 240   end
 241
 242   def mute_operation, do: :ok
 243   def unmute_operation, do: :ok
 244   def block_operation, do: :ok
 245   def unblock_operation, do: :ok
 246   def follows_operation, do: :ok
 247   def mutes_operation, do: :ok
 248   def blocks_operation, do: :ok
 249   def endorsements_operation, do: :ok
 250 end