Merge branch 'openapi/notifications' into 'develop'

Add OpenAPI spec for NotificationController

See merge request pleroma/pleroma!2437

6 files changed, 233 insertions, 15 deletions

diff --git a/lib/pleroma/web/api_spec/helpers.ex b/lib/pleroma/web/api_spec/helpers.ex
index ce40fb9e8..df0804486 100644
--- a/lib/pleroma/web/api_spec/helpers.ex
+++ b/lib/pleroma/web/api_spec/helpers.ex
@@ -46,4 +46,12 @@ defmodule Pleroma.Web.ApiSpec.Helpers do
       )
     ]
   end
+
+  def empty_object_response do
+    Operation.response("Empty object", "application/json", %Schema{type: :object, example: %{}})
+  end
+
+  def empty_array_response do
+    Operation.response("Empty array", "application/json", %Schema{type: :array, example: []})
+  end
 end
diff --git a/lib/pleroma/web/api_spec/operations/account_operation.ex b/lib/pleroma/web/api_spec/operations/account_operation.ex
index d3e8bd484..fe9548b1b 100644
--- a/lib/pleroma/web/api_spec/operations/account_operation.ex
+++ b/lib/pleroma/web/api_spec/operations/account_operation.ex
@@ -344,7 +344,7 @@ defmodule Pleroma.Web.ApiSpec.AccountOperation do
       description: "Not implemented",
       security: [%{"oAuth" => ["read:accounts"]}],
       responses: %{
-        200 => Operation.response("Empry array", "application/json", %Schema{type: :array})
+        200 => empty_array_response()
       }
     }
   end
@@ -356,7 +356,7 @@ defmodule Pleroma.Web.ApiSpec.AccountOperation do
       operationId: "AccountController.identity_proofs",
       description: "Not implemented",
       responses: %{
-        200 => Operation.response("Empry array", "application/json", %Schema{type: :array})
+        200 => empty_array_response()
       }
     }
   end
diff --git a/lib/pleroma/web/api_spec/operations/domain_block_operation.ex b/lib/pleroma/web/api_spec/operations/domain_block_operation.ex
index 3b7f51ceb..049bcf931 100644
--- a/lib/pleroma/web/api_spec/operations/domain_block_operation.ex
+++ b/lib/pleroma/web/api_spec/operations/domain_block_operation.ex
@@ -5,7 +5,7 @@
 defmodule Pleroma.Web.ApiSpec.DomainBlockOperation do
   alias OpenApiSpex.Operation
   alias OpenApiSpex.Schema
-  alias Pleroma.Web.ApiSpec.Helpers
+  import Pleroma.Web.ApiSpec.Helpers
 
   def open_api_operation(action) do
     operation = String.to_existing_atom("#{action}_operation")
@@ -46,9 +46,7 @@ defmodule Pleroma.Web.ApiSpec.DomainBlockOperation do
       operationId: "DomainBlockController.create",
       requestBody: domain_block_request(),
       security: [%{"oAuth" => ["follow", "write:blocks"]}],
-      responses: %{
-        200 => Operation.response("Empty object", "application/json", %Schema{type: :object})
-      }
+      responses: %{200 => empty_object_response()}
     }
   end
 
@@ -67,7 +65,7 @@ defmodule Pleroma.Web.ApiSpec.DomainBlockOperation do
   end
 
   defp domain_block_request do
-    Helpers.request_body(
+    request_body(
       "Parameters",
       %Schema{
         type: :object,
diff --git a/lib/pleroma/web/api_spec/operations/notification_operation.ex b/lib/pleroma/web/api_spec/operations/notification_operation.ex
new file mode 100644
index 000000000..c6514f3f2
--- /dev/null
+++ b/lib/pleroma/web/api_spec/operations/notification_operation.ex
@@ -0,0 +1,202 @@
+# Pleroma: A lightweight social networking server
+# Copyright © 2017-2020 Pleroma Authors <https://pleroma.social/>
+# SPDX-License-Identifier: AGPL-3.0-only
+
+defmodule Pleroma.Web.ApiSpec.NotificationOperation do
+  alias OpenApiSpex.Operation
+  alias OpenApiSpex.Operation
+  alias OpenApiSpex.Schema
+  alias Pleroma.Web.ApiSpec.Schemas.Account
+  alias Pleroma.Web.ApiSpec.Schemas.ApiError
+  alias Pleroma.Web.ApiSpec.Schemas.BooleanLike
+  alias Pleroma.Web.ApiSpec.Schemas.Status
+  alias Pleroma.Web.ApiSpec.Schemas.VisibilityScope
+
+  import Pleroma.Web.ApiSpec.Helpers
+
+  def open_api_operation(action) do
+    operation = String.to_existing_atom("#{action}_operation")
+    apply(__MODULE__, operation, [])
+  end
+
+  def index_operation do
+    %Operation{
+      tags: ["Notifications"],
+      summary: "Get all notifications",
+      description:
+        "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.",
+      operationId: "NotificationController.index",
+      security: [%{"oAuth" => ["read:notifications"]}],
+      parameters:
+        [
+          Operation.parameter(
+            :exclude_types,
+            :query,
+            %Schema{type: :array, items: notification_type()},
+            "Array of types to exclude"
+          ),
+          Operation.parameter(
+            :account_id,
+            :query,
+            %Schema{type: :string},
+            "Return only notifications received from this account"
+          ),
+          Operation.parameter(
+            :exclude_visibilities,
+            :query,
+            %Schema{type: :array, items: VisibilityScope},
+            "Exclude the notifications for activities with the given visibilities"
+          ),
+          Operation.parameter(
+            :include_types,
+            :query,
+            %Schema{type: :array, items: notification_type()},
+            "Include the notifications for activities with the given types"
+          ),
+          Operation.parameter(
+            :with_muted,
+            :query,
+            BooleanLike,
+            "Include the notifications from muted users"
+          )
+        ] ++ pagination_params(),
+      responses: %{
+        200 =>
+          Operation.response("Array of notifications", "application/json", %Schema{
+            type: :array,
+            items: notification()
+          }),
+        404 => Operation.response("Error", "application/json", ApiError)
+      }
+    }
+  end
+
+  def show_operation do
+    %Operation{
+      tags: ["Notifications"],
+      summary: "Get a single notification",
+      description: "View information about a notification with a given ID.",
+      operationId: "NotificationController.show",
+      security: [%{"oAuth" => ["read:notifications"]}],
+      parameters: [id_param()],
+      responses: %{
+        200 => Operation.response("Notification", "application/json", notification())
+      }
+    }
+  end
+
+  def clear_operation do
+    %Operation{
+      tags: ["Notifications"],
+      summary: "Dismiss all notifications",
+      description: "Clear all notifications from the server.",
+      operationId: "NotificationController.clear",
+      security: [%{"oAuth" => ["write:notifications"]}],
+      responses: %{200 => empty_object_response()}
+    }
+  end
+
+  def dismiss_operation do
+    %Operation{
+      tags: ["Notifications"],
+      summary: "Dismiss a single notification",
+      description: "Clear a single notification from the server.",
+      operationId: "NotificationController.dismiss",
+      parameters: [id_param()],
+      security: [%{"oAuth" => ["write:notifications"]}],
+      responses: %{200 => empty_object_response()}
+    }
+  end
+
+  def dismiss_via_body_operation do
+    %Operation{
+      tags: ["Notifications"],
+      summary: "Dismiss a single notification",
+      deprecated: true,
+      description: "Clear a single notification from the server.",
+      operationId: "NotificationController.dismiss_via_body",
+      requestBody:
+        request_body(
+          "Parameters",
+          %Schema{type: :object, properties: %{id: %Schema{type: :string}}},
+          required: true
+        ),
+      security: [%{"oAuth" => ["write:notifications"]}],
+      responses: %{200 => empty_object_response()}
+    }
+  end
+
+  def destroy_multiple_operation do
+    %Operation{
+      tags: ["Notifications"],
+      summary: "Dismiss multiple notifications",
+      operationId: "NotificationController.destroy_multiple",
+      security: [%{"oAuth" => ["write:notifications"]}],
+      parameters: [
+        Operation.parameter(
+          :ids,
+          :query,
+          %Schema{type: :array, items: %Schema{type: :string}},
+          "Array of notification IDs to dismiss",
+          required: true
+        )
+      ],
+      responses: %{200 => empty_object_response()}
+    }
+  end
+
+  defp notification do
+    %Schema{
+      title: "Notification",
+      description: "Response schema for a notification",
+      type: :object,
+      properties: %{
+        id: %Schema{type: :string},
+        type: notification_type(),
+        created_at: %Schema{type: :string, format: :"date-time"},
+        account: %Schema{
+          allOf: [Account],
+          description: "The account that performed the action that generated the notification."
+        },
+        status: %Schema{
+          allOf: [Status],
+          description:
+            "Status that was the object of the notification, e.g. in mentions, reblogs, favourites, or polls.",
+          nullable: true
+        }
+      },
+      example: %{
+        "id" => "34975861",
+        "type" => "mention",
+        "created_at" => "2019-11-23T07:49:02.064Z",
+        "account" => Account.schema().example,
+        "status" => Status.schema().example
+      }
+    }
+  end
+
+  defp notification_type do
+    %Schema{
+      type: :string,
+      enum: ["follow", "favourite", "reblog", "mention", "poll", "pleroma:emoji_reaction", "move"],
+      description: """
+      The type of event that resulted in the notification.
+
+      - `follow` - Someone followed you
+      - `mention` - Someone mentioned you in their status
+      - `reblog` - Someone boosted one of your statuses
+      - `favourite` - Someone favourited one of your statuses
+      - `poll` - A poll you have voted in or created has ended
+      - `move` - Someone moved their account
+      - `pleroma:emoji_reaction` - Someone reacted with emoji to your status
+      """
+    }
+  end
+
+  defp id_param do
+    Operation.parameter(:id, :path, :string, "Notification ID",
+      example: "123",
+      required: true
+    )
+  end
+end
diff --git a/lib/pleroma/web/mastodon_api/controllers/notification_controller.ex b/lib/pleroma/web/mastodon_api/controllers/notification_controller.ex
index 311405277..a14c86893 100644
--- a/lib/pleroma/web/mastodon_api/controllers/notification_controller.ex
+++ b/lib/pleroma/web/mastodon_api/controllers/notification_controller.ex
@@ -13,6 +13,8 @@ defmodule Pleroma.Web.MastodonAPI.NotificationController do
 
   @oauth_read_actions [:show, :index]
 
+  plug(OpenApiSpex.Plug.CastAndValidate, render_error: Pleroma.Web.ApiSpec.RenderError)
+
   plug(
     OAuthScopesPlug,
     %{scopes: ["read:notifications"]} when action in @oauth_read_actions
@@ -20,14 +22,16 @@ defmodule Pleroma.Web.MastodonAPI.NotificationController do
 
   plug(OAuthScopesPlug, %{scopes: ["write:notifications"]} when action not in @oauth_read_actions)
 
+  defdelegate open_api_operation(action), to: Pleroma.Web.ApiSpec.NotificationOperation
+
   # GET /api/v1/notifications
-  def index(conn, %{"account_id" => account_id} = params) do
+  def index(conn, %{account_id: account_id} = params) do
     case Pleroma.User.get_cached_by_id(account_id) do
       %{ap_id: account_ap_id} ->
         params =
           params
-          |> Map.delete("account_id")
-          |> Map.put("account_ap_id", account_ap_id)
+          |> Map.delete(:account_id)
+          |> Map.put(:account_ap_id, account_ap_id)
 
         index(conn, params)
 
@@ -39,6 +43,7 @@ defmodule Pleroma.Web.MastodonAPI.NotificationController do
   end
 
   def index(%{assigns: %{user: user}} = conn, params) do
+    params = Map.new(params, fn {k, v} -> {to_string(k), v} end)
     notifications = MastodonAPI.get_notifications(user, params)
 
     conn
@@ -51,7 +56,7 @@ defmodule Pleroma.Web.MastodonAPI.NotificationController do
   end
 
   # GET /api/v1/notifications/:id
-  def show(%{assigns: %{user: user}} = conn, %{"id" => id}) do
+  def show(%{assigns: %{user: user}} = conn, %{id: id}) do
     with {:ok, notification} <- Notification.get(user, id) do
       render(conn, "show.json", notification: notification, for: user)
     else
@@ -69,8 +74,8 @@ defmodule Pleroma.Web.MastodonAPI.NotificationController do
   end
 
   # POST /api/v1/notifications/:id/dismiss
-  # POST /api/v1/notifications/dismiss (deprecated)
-  def dismiss(%{assigns: %{user: user}} = conn, %{"id" => id} = _params) do
+
+  def dismiss(%{assigns: %{user: user}} = conn, %{id: id} = _params) do
     with {:ok, _notif} <- Notification.dismiss(user, id) do
       json(conn, %{})
     else
@@ -81,8 +86,13 @@ defmodule Pleroma.Web.MastodonAPI.NotificationController do
     end
   end
 
+  # POST /api/v1/notifications/dismiss (deprecated)
+  def dismiss_via_body(%{body_params: params} = conn, _) do
+    dismiss(conn, params)
+  end
+
   # DELETE /api/v1/notifications/destroy_multiple
-  def destroy_multiple(%{assigns: %{user: user}} = conn, %{"ids" => ids} = _params) do
+  def destroy_multiple(%{assigns: %{user: user}} = conn, %{ids: ids} = _params) do
     Notification.destroy_multiple(user, ids)
     json(conn, %{})
   end
diff --git a/lib/pleroma/web/router.ex b/lib/pleroma/web/router.ex
index a7e1f2f57..83287a83d 100644
--- a/lib/pleroma/web/router.ex
+++ b/lib/pleroma/web/router.ex
@@ -396,7 +396,7 @@ defmodule Pleroma.Web.Router do
     post("/notifications/clear", NotificationController, :clear)
     delete("/notifications/destroy_multiple", NotificationController, :destroy_multiple)
     # Deprecated: was removed in Mastodon v3, use `/notifications/:id/dismiss` instead
-    post("/notifications/dismiss", NotificationController, :dismiss)
+    post("/notifications/dismiss", NotificationController, :dismiss_via_body)
 
     post("/polls/:id/votes", PollController, :vote)