git.squeep.com Git - akkoma/blob - lib/pleroma/web/api_spec/operations/pleroma_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.PleromaOperation do
   6   alias OpenApiSpex.Operation
   7   alias OpenApiSpex.Schema
   8   alias Pleroma.Web.ApiSpec.NotificationOperation
   9   alias Pleroma.Web.ApiSpec.Schemas.ApiError
  10   alias Pleroma.Web.ApiSpec.Schemas.Conversation
  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 conversation_operation do
  22     %Operation{
  23       tags: ["Conversations"],
  24       summary: "The conversation with the given ID",
  25       parameters: [
  26         Operation.parameter(:id, :path, :string, "Conversation ID",
  27           example: "123",
  28           required: true
  29         )
  30       ],
  31       security: [%{"oAuth" => ["read:statuses"]}],
  32       operationId: "PleromaController.conversation",
  33       responses: %{
  34         200 => Operation.response("Conversation", "application/json", Conversation)
  35       }
  36     }
  37   end
  38
  39   def conversation_statuses_operation do
  40     %Operation{
  41       tags: ["Conversations"],
  42       summary: "Timeline for a given conversation",
  43       parameters: [
  44         Operation.parameter(:id, :path, :string, "Conversation ID",
  45           example: "123",
  46           required: true
  47         )
  48         | pagination_params()
  49       ],
  50       security: [%{"oAuth" => ["read:statuses"]}],
  51       operationId: "PleromaController.conversation_statuses",
  52       responses: %{
  53         200 =>
  54           Operation.response(
  55             "Array of Statuses",
  56             "application/json",
  57             StatusOperation.array_of_statuses()
  58           )
  59       }
  60     }
  61   end
  62
  63   def update_conversation_operation do
  64     %Operation{
  65       tags: ["Conversations"],
  66       summary: "Update a conversation. Used to change the set of recipients.",
  67       parameters: [
  68         Operation.parameter(:id, :path, :string, "Conversation ID",
  69           example: "123",
  70           required: true
  71         ),
  72         Operation.parameter(
  73           :recipients,
  74           :query,
  75           %Schema{type: :array, items: FlakeID},
  76           "A list of ids of users that should receive posts to this conversation. This will replace the current list of recipients, so submit the full list. The owner of owner of the conversation will always be part of the set of recipients, though.",
  77           required: true
  78         )
  79       ],
  80       security: [%{"oAuth" => ["write:conversations"]}],
  81       operationId: "PleromaController.update_conversation",
  82       responses: %{
  83         200 => Operation.response("Conversation", "application/json", Conversation)
  84       }
  85     }
  86   end
  87
  88   def mark_conversations_as_read_operation do
  89     %Operation{
  90       tags: ["Conversations"],
  91       summary: "Marks all user's conversations as read",
  92       security: [%{"oAuth" => ["write:conversations"]}],
  93       operationId: "PleromaController.mark_conversations_as_read",
  94       responses: %{
  95         200 =>
  96           Operation.response(
  97             "Array of Conversations that were marked as read",
  98             "application/json",
  99             %Schema{
 100               type: :array,
 101               items: Conversation,
 102               example: [Conversation.schema().example]
 103             }
 104           )
 105       }
 106     }
 107   end
 108
 109   def mark_notifications_as_read_operation do
 110     %Operation{
 111       tags: ["Notifications"],
 112       summary: "Mark notifications as read. Query parameters are mutually exclusive.",
 113       parameters: [
 114         Operation.parameter(:id, :query, :string, "A single notification ID to read"),
 115         Operation.parameter(:max_id, :query, :string, "Read all notifications up to this id")
 116       ],
 117       security: [%{"oAuth" => ["write:notifications"]}],
 118       operationId: "PleromaController.mark_notifications_as_read",
 119       responses: %{
 120         200 =>
 121           Operation.response(
 122             "A Notification or array of Motifications",
 123             "application/json",
 124             %Schema{
 125               anyOf: [
 126                 %Schema{type: :array, items: NotificationOperation.notification()},
 127                 NotificationOperation.notification()
 128               ]
 129             }
 130           ),
 131         400 => Operation.response("Bad Request", "application/json", ApiError)
 132       }
 133     }
 134   end
 135 end