git.squeep.com Git - akkoma/blob - lib/pleroma/web/api_spec/operations/admin/user_operation.ex

   1 # Pleroma: A lightweight social networking server
   2 # Copyright © 2017-2021 Pleroma Authors <https://pleroma.social/>
   3 # SPDX-License-Identifier: AGPL-3.0-only
   4
   5 defmodule Pleroma.Web.ApiSpec.Admin.UserOperation do
   6   alias OpenApiSpex.Operation
   7   alias OpenApiSpex.Schema
   8   alias Pleroma.Web.ApiSpec.Schemas.ActorType
   9   alias Pleroma.Web.ApiSpec.Schemas.ApiError
  10
  11   import Pleroma.Web.ApiSpec.Helpers
  12
  13   def open_api_operation(action) do
  14     operation = String.to_existing_atom("#{action}_operation")
  15     apply(__MODULE__, operation, [])
  16   end
  17
  18   def index_operation do
  19     %Operation{
  20       tags: ["User administration"],
  21       summary: "List users",
  22       operationId: "AdminAPI.UserController.index",
  23       security: [%{"oAuth" => ["admin:read:accounts"]}],
  24       parameters: [
  25         Operation.parameter(:filters, :query, :string, "Comma separated list of filters"),
  26         Operation.parameter(:query, :query, :string, "Search users query"),
  27         Operation.parameter(:name, :query, :string, "Search by display name"),
  28         Operation.parameter(:email, :query, :string, "Search by email"),
  29         Operation.parameter(:page, :query, :integer, "Page Number"),
  30         Operation.parameter(:page_size, :query, :integer, "Number of users to return per page"),
  31         Operation.parameter(
  32           :actor_types,
  33           :query,
  34           %Schema{type: :array, items: ActorType},
  35           "Filter by actor type"
  36         ),
  37         Operation.parameter(
  38           :tags,
  39           :query,
  40           %Schema{type: :array, items: %Schema{type: :string}},
  41           "Filter by tags"
  42         )
  43         | admin_api_params()
  44       ],
  45       responses: %{
  46         200 =>
  47           Operation.response(
  48             "Response",
  49             "application/json",
  50             %Schema{
  51               type: :object,
  52               properties: %{
  53                 users: %Schema{type: :array, items: user()},
  54                 count: %Schema{type: :integer},
  55                 page_size: %Schema{type: :integer}
  56               }
  57             }
  58           ),
  59         403 => Operation.response("Forbidden", "application/json", ApiError)
  60       }
  61     }
  62   end
  63
  64   def create_operation do
  65     %Operation{
  66       tags: ["User administration"],
  67       summary: "Create a single or multiple users",
  68       operationId: "AdminAPI.UserController.create",
  69       security: [%{"oAuth" => ["admin:write:accounts"]}],
  70       parameters: admin_api_params(),
  71       requestBody:
  72         request_body(
  73           "Parameters",
  74           %Schema{
  75             description: "POST body for creating users",
  76             type: :object,
  77             properties: %{
  78               users: %Schema{
  79                 type: :array,
  80                 items: %Schema{
  81                   type: :object,
  82                   properties: %{
  83                     nickname: %Schema{type: :string},
  84                     email: %Schema{type: :string},
  85                     password: %Schema{type: :string}
  86                   }
  87                 }
  88               }
  89             }
  90           }
  91         ),
  92       responses: %{
  93         200 =>
  94           Operation.response("Response", "application/json", %Schema{
  95             type: :array,
  96             items: %Schema{
  97               type: :object,
  98               properties: %{
  99                 code: %Schema{type: :integer},
 100                 type: %Schema{type: :string},
 101                 data: %Schema{
 102                   type: :object,
 103                   properties: %{
 104                     email: %Schema{type: :string, format: :email},
 105                     nickname: %Schema{type: :string}
 106                   }
 107                 }
 108               }
 109             }
 110           }),
 111         403 => Operation.response("Forbidden", "application/json", ApiError),
 112         409 =>
 113           Operation.response("Conflict", "application/json", %Schema{
 114             type: :array,
 115             items: %Schema{
 116               type: :object,
 117               properties: %{
 118                 code: %Schema{type: :integer},
 119                 error: %Schema{type: :string},
 120                 type: %Schema{type: :string},
 121                 data: %Schema{
 122                   type: :object,
 123                   properties: %{
 124                     email: %Schema{type: :string, format: :email},
 125                     nickname: %Schema{type: :string}
 126                   }
 127                 }
 128               }
 129             }
 130           })
 131       }
 132     }
 133   end
 134
 135   def show_operation do
 136     %Operation{
 137       tags: ["User administration"],
 138       summary: "Show user",
 139       operationId: "AdminAPI.UserController.show",
 140       security: [%{"oAuth" => ["admin:read:accounts"]}],
 141       parameters: [
 142         Operation.parameter(
 143           :nickname,
 144           :path,
 145           :string,
 146           "User nickname or ID"
 147         )
 148         | admin_api_params()
 149       ],
 150       responses: %{
 151         200 => Operation.response("Response", "application/json", user()),
 152         403 => Operation.response("Forbidden", "application/json", ApiError),
 153         404 => Operation.response("Not Found", "application/json", ApiError)
 154       }
 155     }
 156   end
 157
 158   def follow_operation do
 159     %Operation{
 160       tags: ["User administration"],
 161       summary: "Follow",
 162       operationId: "AdminAPI.UserController.follow",
 163       security: [%{"oAuth" => ["admin:write:follows"]}],
 164       parameters: admin_api_params(),
 165       requestBody:
 166         request_body(
 167           "Parameters",
 168           %Schema{
 169             type: :object,
 170             properties: %{
 171               follower: %Schema{type: :string, description: "Follower nickname"},
 172               followed: %Schema{type: :string, description: "Followed nickname"}
 173             }
 174           }
 175         ),
 176       responses: %{
 177         200 => Operation.response("Response", "application/json", %Schema{type: :string}),
 178         403 => Operation.response("Forbidden", "application/json", ApiError)
 179       }
 180     }
 181   end
 182
 183   def unfollow_operation do
 184     %Operation{
 185       tags: ["User administration"],
 186       summary: "Unfollow",
 187       operationId: "AdminAPI.UserController.unfollow",
 188       security: [%{"oAuth" => ["admin:write:follows"]}],
 189       parameters: admin_api_params(),
 190       requestBody:
 191         request_body(
 192           "Parameters",
 193           %Schema{
 194             type: :object,
 195             properties: %{
 196               follower: %Schema{type: :string, description: "Follower nickname"},
 197               followed: %Schema{type: :string, description: "Followed nickname"}
 198             }
 199           }
 200         ),
 201       responses: %{
 202         200 => Operation.response("Response", "application/json", %Schema{type: :string}),
 203         403 => Operation.response("Forbidden", "application/json", ApiError)
 204       }
 205     }
 206   end
 207
 208   def approve_operation do
 209     %Operation{
 210       tags: ["User administration"],
 211       summary: "Approve multiple users",
 212       operationId: "AdminAPI.UserController.approve",
 213       security: [%{"oAuth" => ["admin:write:accounts"]}],
 214       parameters: admin_api_params(),
 215       requestBody:
 216         request_body(
 217           "Parameters",
 218           %Schema{
 219             description: "POST body for approving multiple users",
 220             type: :object,
 221             properties: %{
 222               nicknames: %Schema{
 223                 type: :array,
 224                 items: %Schema{type: :string}
 225               }
 226             }
 227           }
 228         ),
 229       responses: %{
 230         200 =>
 231           Operation.response("Response", "application/json", %Schema{
 232             type: :object,
 233             properties: %{user: %Schema{type: :array, items: user()}}
 234           }),
 235         403 => Operation.response("Forbidden", "application/json", ApiError)
 236       }
 237     }
 238   end
 239
 240   def suggest_operation do
 241     %Operation{
 242       tags: ["User administration"],
 243       summary: "Suggest multiple users",
 244       operationId: "AdminAPI.UserController.suggest",
 245       security: [%{"oAuth" => ["admin:write:accounts"]}],
 246       parameters: admin_api_params(),
 247       requestBody:
 248         request_body(
 249           "Parameters",
 250           %Schema{
 251             description: "POST body for adding multiple suggested users",
 252             type: :object,
 253             properties: %{
 254               nicknames: %Schema{
 255                 type: :array,
 256                 items: %Schema{type: :string}
 257               }
 258             }
 259           }
 260         ),
 261       responses: %{
 262         200 =>
 263           Operation.response("Response", "application/json", %Schema{
 264             type: :object,
 265             properties: %{user: %Schema{type: :array, items: user()}}
 266           }),
 267         403 => Operation.response("Forbidden", "application/json", ApiError)
 268       }
 269     }
 270   end
 271
 272   def unsuggest_operation do
 273     %Operation{
 274       tags: ["User administration"],
 275       summary: "Unsuggest multiple users",
 276       operationId: "AdminAPI.UserController.unsuggest",
 277       security: [%{"oAuth" => ["admin:write:accounts"]}],
 278       parameters: admin_api_params(),
 279       requestBody:
 280         request_body(
 281           "Parameters",
 282           %Schema{
 283             description: "POST body for removing multiple suggested users",
 284             type: :object,
 285             properties: %{
 286               nicknames: %Schema{
 287                 type: :array,
 288                 items: %Schema{type: :string}
 289               }
 290             }
 291           }
 292         ),
 293       responses: %{
 294         200 =>
 295           Operation.response("Response", "application/json", %Schema{
 296             type: :object,
 297             properties: %{user: %Schema{type: :array, items: user()}}
 298           }),
 299         403 => Operation.response("Forbidden", "application/json", ApiError)
 300       }
 301     }
 302   end
 303
 304   def toggle_activation_operation do
 305     %Operation{
 306       tags: ["User administration"],
 307       summary: "Toggle user activation",
 308       operationId: "AdminAPI.UserController.toggle_activation",
 309       security: [%{"oAuth" => ["admin:write:accounts"]}],
 310       parameters: [
 311         Operation.parameter(:nickname, :path, :string, "User nickname")
 312         | admin_api_params()
 313       ],
 314       responses: %{
 315         200 => Operation.response("Response", "application/json", user()),
 316         403 => Operation.response("Forbidden", "application/json", ApiError)
 317       }
 318     }
 319   end
 320
 321   def activate_operation do
 322     %Operation{
 323       tags: ["User administration"],
 324       summary: "Activate multiple users",
 325       operationId: "AdminAPI.UserController.activate",
 326       security: [%{"oAuth" => ["admin:write:accounts"]}],
 327       parameters: admin_api_params(),
 328       requestBody:
 329         request_body(
 330           "Parameters",
 331           %Schema{
 332             description: "POST body for deleting multiple users",
 333             type: :object,
 334             properties: %{
 335               nicknames: %Schema{
 336                 type: :array,
 337                 items: %Schema{type: :string}
 338               }
 339             }
 340           }
 341         ),
 342       responses: %{
 343         200 =>
 344           Operation.response("Response", "application/json", %Schema{
 345             type: :object,
 346             properties: %{user: %Schema{type: :array, items: user()}}
 347           }),
 348         403 => Operation.response("Forbidden", "application/json", ApiError)
 349       }
 350     }
 351   end
 352
 353   def deactivate_operation do
 354     %Operation{
 355       tags: ["User administration"],
 356       summary: "Deactivates multiple users",
 357       operationId: "AdminAPI.UserController.deactivate",
 358       security: [%{"oAuth" => ["admin:write:accounts"]}],
 359       parameters: admin_api_params(),
 360       requestBody:
 361         request_body(
 362           "Parameters",
 363           %Schema{
 364             description: "POST body for deleting multiple users",
 365             type: :object,
 366             properties: %{
 367               nicknames: %Schema{
 368                 type: :array,
 369                 items: %Schema{type: :string}
 370               }
 371             }
 372           }
 373         ),
 374       responses: %{
 375         200 =>
 376           Operation.response("Response", "application/json", %Schema{
 377             type: :object,
 378             properties: %{user: %Schema{type: :array, items: user()}}
 379           }),
 380         403 => Operation.response("Forbidden", "application/json", ApiError)
 381       }
 382     }
 383   end
 384
 385   def delete_operation do
 386     %Operation{
 387       tags: ["User administration"],
 388       summary: "Removes a single or multiple users",
 389       operationId: "AdminAPI.UserController.delete",
 390       security: [%{"oAuth" => ["admin:write:accounts"]}],
 391       parameters: [
 392         Operation.parameter(
 393           :nickname,
 394           :query,
 395           :string,
 396           "User nickname"
 397         )
 398         | admin_api_params()
 399       ],
 400       requestBody:
 401         request_body(
 402           "Parameters",
 403           %Schema{
 404             description: "POST body for deleting multiple users",
 405             type: :object,
 406             properties: %{
 407               nicknames: %Schema{
 408                 type: :array,
 409                 items: %Schema{type: :string}
 410               }
 411             }
 412           }
 413         ),
 414       responses: %{
 415         200 =>
 416           Operation.response("Response", "application/json", %Schema{
 417             description: "Array of nicknames",
 418             type: :array,
 419             items: %Schema{type: :string}
 420           }),
 421         403 => Operation.response("Forbidden", "application/json", ApiError)
 422       }
 423     }
 424   end
 425
 426   defp user do
 427     %Schema{
 428       type: :object,
 429       properties: %{
 430         id: %Schema{type: :string},
 431         email: %Schema{type: :string, format: :email},
 432         avatar: %Schema{type: :string, format: :uri},
 433         nickname: %Schema{type: :string},
 434         display_name: %Schema{type: :string},
 435         is_active: %Schema{type: :boolean},
 436         local: %Schema{type: :boolean},
 437         roles: %Schema{
 438           type: :object,
 439           properties: %{
 440             admin: %Schema{type: :boolean},
 441             moderator: %Schema{type: :boolean}
 442           }
 443         },
 444         tags: %Schema{type: :array, items: %Schema{type: :string}},
 445         is_confirmed: %Schema{type: :boolean},
 446         is_approved: %Schema{type: :boolean},
 447         url: %Schema{type: :string, format: :uri},
 448         registration_reason: %Schema{type: :string, nullable: true},
 449         actor_type: %Schema{type: :string}
 450       }
 451     }
 452   end
 453 end