First
[anni] / lib / pleroma / web / api_spec / operations / admin / user_operation.ex
1 # Pleroma: A lightweight social networking server
2 # Copyright © 2017-2022 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