total rebase
[anni] / lib / pleroma / web / api_spec / operations / pleroma_account_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.PleromaAccountOperation do
6   alias OpenApiSpex.Operation
7   alias OpenApiSpex.Schema
8   alias Pleroma.Web.ApiSpec.AccountOperation
9   alias Pleroma.Web.ApiSpec.Schemas.AccountRelationship
10   alias Pleroma.Web.ApiSpec.Schemas.ApiError
11   alias Pleroma.Web.ApiSpec.Schemas.FlakeID
12   alias Pleroma.Web.ApiSpec.StatusOperation
13
14   import Pleroma.Web.ApiSpec.Helpers
15
16   def open_api_operation(action) do
17     operation = String.to_existing_atom("#{action}_operation")
18     apply(__MODULE__, operation, [])
19   end
20
21   def confirmation_resend_operation do
22     %Operation{
23       tags: ["Account credentials"],
24       summary: "Resend confirmation email",
25       description: "Expects `email` or `nickname`.",
26       operationId: "PleromaAPI.AccountController.confirmation_resend",
27       parameters: [
28         Operation.parameter(:email, :query, :string, "Email of that needs to be verified",
29           example: "cofe@cofe.io"
30         ),
31         Operation.parameter(
32           :nickname,
33           :query,
34           :string,
35           "Nickname of user that needs to be verified",
36           example: "cofefe"
37         )
38       ],
39       responses: %{
40         204 => no_content_response()
41       }
42     }
43   end
44
45   def favourites_operation do
46     %Operation{
47       tags: ["Retrieve account information"],
48       summary: "Favorites",
49       description:
50         "Only returns data if the user has opted into sharing it. See `hide_favorites` in [Update account credentials](#operation/AccountController.update_credentials).",
51       operationId: "PleromaAPI.AccountController.favourites",
52       parameters: [id_param() | pagination_params()],
53       security: [%{"oAuth" => ["read:favourites"]}],
54       responses: %{
55         200 =>
56           Operation.response(
57             "Array of Statuses",
58             "application/json",
59             StatusOperation.array_of_statuses()
60           ),
61         403 => Operation.response("Forbidden", "application/json", ApiError),
62         404 => Operation.response("Not Found", "application/json", ApiError)
63       }
64     }
65   end
66
67   def endorsements_operation do
68     %Operation{
69       tags: ["Retrieve account information"],
70       summary: "Endorsements",
71       description: "Returns endorsed accounts",
72       operationId: "PleromaAPI.AccountController.endorsements",
73       parameters: [with_relationships_param(), id_param()],
74       responses: %{
75         200 =>
76           Operation.response(
77             "Array of Accounts",
78             "application/json",
79             AccountOperation.array_of_accounts()
80           ),
81         404 => Operation.response("Not Found", "application/json", ApiError)
82       }
83     }
84   end
85
86   def subscribe_operation do
87     %Operation{
88       tags: ["Account actions"],
89       summary: "Subscribe",
90       description: "Receive notifications for all statuses posted by the account.",
91       operationId: "PleromaAPI.AccountController.subscribe",
92       parameters: [id_param()],
93       security: [%{"oAuth" => ["follow", "write:follows"]}],
94       responses: %{
95         200 => Operation.response("Relationship", "application/json", AccountRelationship),
96         404 => Operation.response("Not Found", "application/json", ApiError)
97       }
98     }
99   end
100
101   def unsubscribe_operation do
102     %Operation{
103       tags: ["Account actions"],
104       summary: "Unsubscribe",
105       description: "Stop receiving notifications for all statuses posted by the account.",
106       operationId: "PleromaAPI.AccountController.unsubscribe",
107       parameters: [id_param()],
108       security: [%{"oAuth" => ["follow", "write:follows"]}],
109       responses: %{
110         200 => Operation.response("Relationship", "application/json", AccountRelationship),
111         404 => Operation.response("Not Found", "application/json", ApiError)
112       }
113     }
114   end
115
116   def birthdays_operation do
117     %Operation{
118       tags: ["Retrieve account information"],
119       summary: "Birthday reminders",
120       description: "Birthday reminders about users you follow.",
121       operationId: "PleromaAPI.AccountController.birthdays",
122       parameters: [
123         Operation.parameter(
124           :day,
125           :query,
126           %Schema{type: :integer},
127           "Day of users' birthdays"
128         ),
129         Operation.parameter(
130           :month,
131           :query,
132           %Schema{type: :integer},
133           "Month of users' birthdays"
134         )
135       ],
136       security: [%{"oAuth" => ["read:accounts"]}],
137       responses: %{
138         200 =>
139           Operation.response("Accounts", "application/json", AccountOperation.array_of_accounts())
140       }
141     }
142   end
143
144   defp id_param do
145     Operation.parameter(:id, :path, FlakeID.schema(), "Account ID",
146       example: "9umDrYheeY451cQnEe",
147       required: true
148     )
149   end
150 end