git.squeep.com Git - akkoma/blob - lib/pleroma/web/api_spec/operations/timeline_operation.ex

   1 # Pleroma: A lightweight social networking server
   2 # Copyright © 2017-2021 Pleroma Authors <https://pleroma.social/>
   3 # SPDX-License-Identifier: AGPL-3.0-only
   4
   5 defmodule Pleroma.Web.ApiSpec.TimelineOperation do
   6   alias OpenApiSpex.Operation
   7   alias OpenApiSpex.Schema
   8   alias Pleroma.Web.ApiSpec.Schemas.ApiError
   9   alias Pleroma.Web.ApiSpec.Schemas.BooleanLike
  10   alias Pleroma.Web.ApiSpec.Schemas.Status
  11   alias Pleroma.Web.ApiSpec.Schemas.VisibilityScope
  12
  13   import Pleroma.Web.ApiSpec.Helpers
  14
  15   def open_api_operation(action) do
  16     operation = String.to_existing_atom("#{action}_operation")
  17     apply(__MODULE__, operation, [])
  18   end
  19
  20   def home_operation do
  21     %Operation{
  22       tags: ["Timelines"],
  23       summary: "Home timeline",
  24       description: "View statuses from followed users",
  25       security: [%{"oAuth" => ["read:statuses"]}],
  26       parameters: [
  27         local_param(),
  28         remote_param(),
  29         only_media_param(),
  30         with_muted_param(),
  31         exclude_visibilities_param(),
  32         reply_visibility_param() | pagination_params()
  33       ],
  34       operationId: "TimelineController.home",
  35       responses: %{
  36         200 => Operation.response("Array of Status", "application/json", array_of_statuses())
  37       }
  38     }
  39   end
  40
  41   def direct_operation do
  42     %Operation{
  43       tags: ["Timelines"],
  44       summary: "Direct timeline",
  45       description:
  46         "View statuses with a “direct” scope addressed to the account. Using this endpoint is discouraged, please use [conversations](#tag/Conversations).",
  47       parameters: [with_muted_param() | pagination_params()],
  48       security: [%{"oAuth" => ["read:statuses"]}],
  49       operationId: "TimelineController.direct",
  50       responses: %{
  51         200 => Operation.response("Array of Status", "application/json", array_of_statuses())
  52       }
  53     }
  54   end
  55
  56   def public_operation do
  57     %Operation{
  58       tags: ["Timelines"],
  59       summary: "Public timeline",
  60       security: [%{"oAuth" => ["read:statuses"]}],
  61       parameters: [
  62         local_param(),
  63         instance_param(),
  64         only_media_param(),
  65         remote_param(),
  66         with_muted_param(),
  67         exclude_visibilities_param(),
  68         reply_visibility_param() | pagination_params()
  69       ],
  70       operationId: "TimelineController.public",
  71       responses: %{
  72         200 => Operation.response("Array of Status", "application/json", array_of_statuses()),
  73         401 => Operation.response("Error", "application/json", ApiError),
  74         404 => Operation.response("Error", "application/json", ApiError)
  75       }
  76     }
  77   end
  78
  79   def bubble_operation do
  80     %Operation{
  81       tags: ["Timelines"],
  82       summary: "Bubble timeline",
  83       security: [%{"oAuth" => ["read:statuses"]}],
  84       parameters: [
  85         only_media_param(),
  86         remote_param(),
  87         with_muted_param(),
  88         exclude_visibilities_param(),
  89         reply_visibility_param() | pagination_params()
  90       ],
  91       operationId: "TimelineController.bubble",
  92       responses: %{
  93         200 => Operation.response("Array of Status", "application/json", array_of_statuses()),
  94         401 => Operation.response("Error", "application/json", ApiError)
  95       }
  96     }
  97   end
  98
  99   def hashtag_operation do
 100     %Operation{
 101       tags: ["Timelines"],
 102       summary: "Hashtag timeline",
 103       description: "View public statuses containing the given hashtag",
 104       security: [%{"oAuth" => ["read:statuses"]}],
 105       parameters: [
 106         Operation.parameter(
 107           :tag,
 108           :path,
 109           %Schema{type: :string},
 110           "Content of a #hashtag, not including # symbol.",
 111           required: true
 112         ),
 113         Operation.parameter(
 114           :any,
 115           :query,
 116           %Schema{type: :array, items: %Schema{type: :string}},
 117           "Statuses that also includes any of these tags"
 118         ),
 119         Operation.parameter(
 120           :all,
 121           :query,
 122           %Schema{type: :array, items: %Schema{type: :string}},
 123           "Statuses that also includes all of these tags"
 124         ),
 125         Operation.parameter(
 126           :none,
 127           :query,
 128           %Schema{type: :array, items: %Schema{type: :string}},
 129           "Statuses that do not include these tags"
 130         ),
 131         local_param(),
 132         only_media_param(),
 133         remote_param(),
 134         with_muted_param(),
 135         exclude_visibilities_param() | pagination_params()
 136       ],
 137       operationId: "TimelineController.hashtag",
 138       responses: %{
 139         200 => Operation.response("Array of Status", "application/json", array_of_statuses()),
 140         401 => Operation.response("Error", "application/json", ApiError)
 141       }
 142     }
 143   end
 144
 145   def list_operation do
 146     %Operation{
 147       tags: ["Timelines"],
 148       summary: "List timeline",
 149       description: "View statuses in the given list timeline",
 150       security: [%{"oAuth" => ["read:lists"]}],
 151       parameters: [
 152         Operation.parameter(
 153           :list_id,
 154           :path,
 155           %Schema{type: :string},
 156           "Local ID of the list in the database",
 157           required: true
 158         ),
 159         with_muted_param(),
 160         local_param(),
 161         remote_param(),
 162         only_media_param(),
 163         exclude_visibilities_param() | pagination_params()
 164       ],
 165       operationId: "TimelineController.list",
 166       responses: %{
 167         200 => Operation.response("Array of Status", "application/json", array_of_statuses())
 168       }
 169     }
 170   end
 171
 172   defp array_of_statuses do
 173     %Schema{
 174       title: "ArrayOfStatuses",
 175       type: :array,
 176       items: Status,
 177       example: [Status.schema().example]
 178     }
 179   end
 180
 181   defp local_param do
 182     Operation.parameter(
 183       :local,
 184       :query,
 185       %Schema{allOf: [BooleanLike], default: false},
 186       "Show only local statuses?"
 187     )
 188   end
 189
 190   defp instance_param do
 191     Operation.parameter(
 192       :instance,
 193       :query,
 194       %Schema{type: :string},
 195       "Show only statuses from the given domain"
 196     )
 197   end
 198
 199   defp with_muted_param do
 200     Operation.parameter(:with_muted, :query, BooleanLike, "Include activities by muted users")
 201   end
 202
 203   defp exclude_visibilities_param do
 204     Operation.parameter(
 205       :exclude_visibilities,
 206       :query,
 207       %Schema{type: :array, items: VisibilityScope},
 208       "Exclude the statuses with the given visibilities"
 209     )
 210   end
 211
 212   defp reply_visibility_param do
 213     Operation.parameter(
 214       :reply_visibility,
 215       :query,
 216       %Schema{type: :string, enum: ["following", "self"]},
 217       "Filter replies. Possible values: without parameter (default) shows all replies, `following` - replies directed to you or users you follow, `self` - replies directed to you."
 218     )
 219   end
 220
 221   defp only_media_param do
 222     Operation.parameter(
 223       :only_media,
 224       :query,
 225       %Schema{allOf: [BooleanLike], default: false},
 226       "Show only statuses with media attached?"
 227     )
 228   end
 229
 230   defp remote_param do
 231     Operation.parameter(
 232       :remote,
 233       :query,
 234       %Schema{allOf: [BooleanLike], default: false},
 235       "Show only remote statuses?"
 236     )
 237   end
 238 end