Git of dcc - anni/blob - 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,
  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