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