total rebase
[anni] / lib / pleroma / web / api_spec / operations / notification_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.NotificationOperation do
6   alias OpenApiSpex.Operation
7   alias OpenApiSpex.Operation
8   alias OpenApiSpex.Schema
9   alias Pleroma.Web.ApiSpec.Schemas.Account
10   alias Pleroma.Web.ApiSpec.Schemas.ApiError
11   alias Pleroma.Web.ApiSpec.Schemas.BooleanLike
12   alias Pleroma.Web.ApiSpec.Schemas.Status
13   alias Pleroma.Web.ApiSpec.Schemas.VisibilityScope
14
15   import Pleroma.Web.ApiSpec.Helpers
16
17   def open_api_operation(action) do
18     operation = String.to_existing_atom("#{action}_operation")
19     apply(__MODULE__, operation, [])
20   end
21
22   def index_operation do
23     %Operation{
24       tags: ["Notifications"],
25       summary: "Retrieve a list of notifications",
26       description:
27         "Notifications concerning the user. This API returns Link headers containing links to the next/previous page. However, the links can also be constructed dynamically using query params and `id` values.",
28       operationId: "NotificationController.index",
29       security: [%{"oAuth" => ["read:notifications"]}],
30       parameters:
31         [
32           Operation.parameter(
33             :exclude_types,
34             :query,
35             %Schema{type: :array, items: notification_type()},
36             "Array of types to exclude"
37           ),
38           Operation.parameter(
39             :account_id,
40             :query,
41             %Schema{type: :string},
42             "Return only notifications received from this account"
43           ),
44           Operation.parameter(
45             :exclude_visibilities,
46             :query,
47             %Schema{type: :array, items: VisibilityScope},
48             "Exclude the notifications for activities with the given visibilities"
49           ),
50           Operation.parameter(
51             :include_types,
52             :query,
53             %Schema{type: :array, items: notification_type()},
54             "Deprecated, use `types` instead"
55           ),
56           Operation.parameter(
57             :types,
58             :query,
59             %Schema{type: :array, items: notification_type()},
60             "Include the notifications for activities with the given types"
61           ),
62           Operation.parameter(
63             :with_muted,
64             :query,
65             BooleanLike.schema(),
66             "Include the notifications from muted users"
67           )
68         ] ++ pagination_params(),
69       responses: %{
70         200 =>
71           Operation.response("Array of notifications", "application/json", %Schema{
72             type: :array,
73             items: notification()
74           }),
75         404 => Operation.response("Error", "application/json", ApiError)
76       }
77     }
78   end
79
80   def show_operation do
81     %Operation{
82       tags: ["Notifications"],
83       summary: "Retrieve a notification",
84       description: "View information about a notification with a given ID.",
85       operationId: "NotificationController.show",
86       security: [%{"oAuth" => ["read:notifications"]}],
87       parameters: [id_param()],
88       responses: %{
89         200 => Operation.response("Notification", "application/json", notification())
90       }
91     }
92   end
93
94   def clear_operation do
95     %Operation{
96       tags: ["Notifications"],
97       summary: "Dismiss all notifications",
98       description: "Clear all notifications from the server.",
99       operationId: "NotificationController.clear",
100       security: [%{"oAuth" => ["write:notifications"]}],
101       responses: %{200 => empty_object_response()}
102     }
103   end
104
105   def dismiss_operation do
106     %Operation{
107       tags: ["Notifications"],
108       summary: "Dismiss a notification",
109       description: "Clear a single notification from the server.",
110       operationId: "NotificationController.dismiss",
111       parameters: [id_param()],
112       security: [%{"oAuth" => ["write:notifications"]}],
113       responses: %{200 => empty_object_response()}
114     }
115   end
116
117   def dismiss_via_body_operation do
118     %Operation{
119       tags: ["Notifications"],
120       summary: "Dismiss a single notification",
121       deprecated: true,
122       description: "Clear a single notification from the server.",
123       operationId: "NotificationController.dismiss_via_body",
124       requestBody:
125         request_body(
126           "Parameters",
127           %Schema{type: :object, properties: %{id: %Schema{type: :string}}},
128           required: true
129         ),
130       security: [%{"oAuth" => ["write:notifications"]}],
131       responses: %{200 => empty_object_response()}
132     }
133   end
134
135   def destroy_multiple_operation do
136     %Operation{
137       tags: ["Notifications"],
138       summary: "Dismiss multiple notifications",
139       operationId: "NotificationController.destroy_multiple",
140       security: [%{"oAuth" => ["write:notifications"]}],
141       parameters: [
142         Operation.parameter(
143           :ids,
144           :query,
145           %Schema{type: :array, items: %Schema{type: :string}},
146           "Array of notification IDs to dismiss",
147           required: true
148         )
149       ],
150       responses: %{200 => empty_object_response()}
151     }
152   end
153
154   def notification do
155     %Schema{
156       title: "Notification",
157       description: "Response schema for a notification",
158       type: :object,
159       properties: %{
160         id: %Schema{type: :string},
161         type: notification_type(),
162         created_at: %Schema{type: :string, format: :"date-time"},
163         account: %Schema{
164           allOf: [Account],
165           description: "The account that performed the action that generated the notification."
166         },
167         status: %Schema{
168           allOf: [Status],
169           description:
170             "Status that was the object of the notification, e.g. in mentions, reblogs, favourites, or polls.",
171           nullable: true
172         },
173         pleroma: %Schema{
174           type: :object,
175           properties: %{
176             is_seen: %Schema{type: :boolean},
177             is_muted: %Schema{type: :boolean}
178           }
179         }
180       },
181       example: %{
182         "id" => "34975861",
183         "type" => "mention",
184         "created_at" => "2019-11-23T07:49:02.064Z",
185         "account" => Account.schema().example,
186         "status" => Status.schema().example,
187         "pleroma" => %{"is_seen" => false, "is_muted" => false}
188       }
189     }
190   end
191
192   defp notification_type do
193     %Schema{
194       type: :string,
195       enum: [
196         "follow",
197         "favourite",
198         "reblog",
199         "mention",
200         "pleroma:emoji_reaction",
201         "pleroma:chat_mention",
202         "pleroma:report",
203         "move",
204         "follow_request",
205         "poll"
206       ],
207       description: """
208       The type of event that resulted in the notification.
209
210       - `follow` - Someone followed you
211       - `mention` - Someone mentioned you in their status
212       - `reblog` - Someone boosted one of your statuses
213       - `favourite` - Someone favourited one of your statuses
214       - `poll` - A poll you have voted in or created has ended
215       - `move` - Someone moved their account
216       - `pleroma:emoji_reaction` - Someone reacted with emoji to your status
217       - `pleroma:chat_mention` - Someone mentioned you in a chat message
218       - `pleroma:report` - Someone was reported
219       """
220     }
221   end
222
223   defp id_param do
224     Operation.parameter(:id, :path, :string, "Notification ID",
225       example: "123",
226       required: true
227     )
228   end
229 end