Remove `poll` from `notification_type` OpenAPI spec
[akkoma] / lib / pleroma / web / api_spec / operations / notification_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.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: "Get all 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 "Include the notifications for activities with the given types"
55 ),
56 Operation.parameter(
57 :with_muted,
58 :query,
59 BooleanLike,
60 "Include the notifications from muted users"
61 )
62 ] ++ pagination_params(),
63 responses: %{
64 200 =>
65 Operation.response("Array of notifications", "application/json", %Schema{
66 type: :array,
67 items: notification()
68 }),
69 404 => Operation.response("Error", "application/json", ApiError)
70 }
71 }
72 end
73
74 def show_operation do
75 %Operation{
76 tags: ["Notifications"],
77 summary: "Get a single notification",
78 description: "View information about a notification with a given ID.",
79 operationId: "NotificationController.show",
80 security: [%{"oAuth" => ["read:notifications"]}],
81 parameters: [id_param()],
82 responses: %{
83 200 => Operation.response("Notification", "application/json", notification())
84 }
85 }
86 end
87
88 def clear_operation do
89 %Operation{
90 tags: ["Notifications"],
91 summary: "Dismiss all notifications",
92 description: "Clear all notifications from the server.",
93 operationId: "NotificationController.clear",
94 security: [%{"oAuth" => ["write:notifications"]}],
95 responses: %{200 => empty_object_response()}
96 }
97 end
98
99 def dismiss_operation do
100 %Operation{
101 tags: ["Notifications"],
102 summary: "Dismiss a single notification",
103 description: "Clear a single notification from the server.",
104 operationId: "NotificationController.dismiss",
105 parameters: [id_param()],
106 security: [%{"oAuth" => ["write:notifications"]}],
107 responses: %{200 => empty_object_response()}
108 }
109 end
110
111 def dismiss_via_body_operation do
112 %Operation{
113 tags: ["Notifications"],
114 summary: "Dismiss a single notification",
115 deprecated: true,
116 description: "Clear a single notification from the server.",
117 operationId: "NotificationController.dismiss_via_body",
118 requestBody:
119 request_body(
120 "Parameters",
121 %Schema{type: :object, properties: %{id: %Schema{type: :string}}},
122 required: true
123 ),
124 security: [%{"oAuth" => ["write:notifications"]}],
125 responses: %{200 => empty_object_response()}
126 }
127 end
128
129 def destroy_multiple_operation do
130 %Operation{
131 tags: ["Notifications"],
132 summary: "Dismiss multiple notifications",
133 operationId: "NotificationController.destroy_multiple",
134 security: [%{"oAuth" => ["write:notifications"]}],
135 parameters: [
136 Operation.parameter(
137 :ids,
138 :query,
139 %Schema{type: :array, items: %Schema{type: :string}},
140 "Array of notification IDs to dismiss",
141 required: true
142 )
143 ],
144 responses: %{200 => empty_object_response()}
145 }
146 end
147
148 def notification do
149 %Schema{
150 title: "Notification",
151 description: "Response schema for a notification",
152 type: :object,
153 properties: %{
154 id: %Schema{type: :string},
155 type: notification_type(),
156 created_at: %Schema{type: :string, format: :"date-time"},
157 account: %Schema{
158 allOf: [Account],
159 description: "The account that performed the action that generated the notification."
160 },
161 status: %Schema{
162 allOf: [Status],
163 description:
164 "Status that was the object of the notification, e.g. in mentions, reblogs, favourites, or polls.",
165 nullable: true
166 }
167 },
168 example: %{
169 "id" => "34975861",
170 "type" => "mention",
171 "created_at" => "2019-11-23T07:49:02.064Z",
172 "account" => Account.schema().example,
173 "status" => Status.schema().example
174 }
175 }
176 end
177
178 defp notification_type do
179 %Schema{
180 type: :string,
181 enum: [
182 "follow",
183 "favourite",
184 "reblog",
185 "mention",
186 "pleroma:emoji_reaction",
187 "pleroma:chat_mention",
188 "move",
189 "follow_request"
190 ],
191 description: """
192 The type of event that resulted in the notification.
193
194 - `follow` - Someone followed you
195 - `mention` - Someone mentioned you in their status
196 - `reblog` - Someone boosted one of your statuses
197 - `favourite` - Someone favourited one of your statuses
198 - `poll` - A poll you have voted in or created has ended
199 - `move` - Someone moved their account
200 - `pleroma:emoji_reaction` - Someone reacted with emoji to your status
201 """
202 }
203 end
204
205 defp id_param do
206 Operation.parameter(:id, :path, :string, "Notification ID",
207 example: "123",
208 required: true
209 )
210 end
211 end