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       }
  75     }
  76   end
  77
  78   def bubble_operation do
  79     %Operation{
  80       tags: ["Timelines"],
  81       summary: "Bubble timeline",
  82       security: [%{"oAuth" => ["read:statuses"]}],
  83       parameters: [
  84         only_media_param(),
  85         remote_param(),
  86         with_muted_param(),
  87         exclude_visibilities_param(),
  88         reply_visibility_param() | pagination_params()
  89       ],
  90       operationId: "TimelineController.bubble",
  91       responses: %{
  92         200 => Operation.response("Array of Status", "application/json", array_of_statuses()),
  93         401 => Operation.response("Error", "application/json", ApiError)
  94       }
  95     }
  96   end
  97
  98   def hashtag_operation do
  99     %Operation{
 100       tags: ["Timelines"],
 101       summary: "Hashtag timeline",
 102       description: "View public statuses containing the given hashtag",
 103       security: [%{"oAuth" => ["read:statuses"]}],
 104       parameters: [
 105         Operation.parameter(
 106           :tag,
 107           :path,
 108           %Schema{type: :string},
 109           "Content of a #hashtag, not including # symbol.",
 110           required: true
 111         ),
 112         Operation.parameter(
 113           :any,
 114           :query,
 115           %Schema{type: :array, items: %Schema{type: :string}},
 116           "Statuses that also includes any of these tags"
 117         ),
 118         Operation.parameter(
 119           :all,
 120           :query,
 121           %Schema{type: :array, items: %Schema{type: :string}},
 122           "Statuses that also includes all of these tags"
 123         ),
 124         Operation.parameter(
 125           :none,
 126           :query,
 127           %Schema{type: :array, items: %Schema{type: :string}},
 128           "Statuses that do not include these tags"
 129         ),
 130         local_param(),
 131         only_media_param(),
 132         remote_param(),
 133         with_muted_param(),
 134         exclude_visibilities_param() | pagination_params()
 135       ],
 136       operationId: "TimelineController.hashtag",
 137       responses: %{
 138         200 => Operation.response("Array of Status", "application/json", array_of_statuses()),
 139         401 => Operation.response("Error", "application/json", ApiError)
 140       }
 141     }
 142   end
 143
 144   def list_operation do
 145     %Operation{
 146       tags: ["Timelines"],
 147       summary: "List timeline",
 148       description: "View statuses in the given list timeline",
 149       security: [%{"oAuth" => ["read:lists"]}],
 150       parameters: [
 151         Operation.parameter(
 152           :list_id,
 153           :path,
 154           %Schema{type: :string},
 155           "Local ID of the list in the database",
 156           required: true
 157         ),
 158         with_muted_param(),
 159         local_param(),
 160         remote_param(),
 161         only_media_param(),
 162         exclude_visibilities_param() | pagination_params()
 163       ],
 164       operationId: "TimelineController.list",
 165       responses: %{
 166         200 => Operation.response("Array of Status", "application/json", array_of_statuses())
 167       }
 168     }
 169   end
 170
 171   defp array_of_statuses do
 172     %Schema{
 173       title: "ArrayOfStatuses",
 174       type: :array,
 175       items: Status,
 176       example: [Status.schema().example]
 177     }
 178   end
 179
 180   defp local_param do
 181     Operation.parameter(
 182       :local,
 183       :query,
 184       %Schema{allOf: [BooleanLike], default: false},
 185       "Show only local statuses?"
 186     )
 187   end
 188
 189   defp instance_param do
 190     Operation.parameter(
 191       :instance,
 192       :query,
 193       %Schema{type: :string},
 194       "Show only statuses from the given domain"
 195     )
 196   end
 197
 198   defp with_muted_param do
 199     Operation.parameter(:with_muted, :query, BooleanLike, "Include activities by muted users")
 200   end
 201
 202   defp exclude_visibilities_param do
 203     Operation.parameter(
 204       :exclude_visibilities,
 205       :query,
 206       %Schema{type: :array, items: VisibilityScope},
 207       "Exclude the statuses with the given visibilities"
 208     )
 209   end
 210
 211   defp reply_visibility_param do
 212     Operation.parameter(
 213       :reply_visibility,
 214       :query,
 215       %Schema{type: :string, enum: ["following", "self"]},
 216       "Filter replies. Possible values: without parameter (default) shows all replies, `following` - replies directed to you or users you follow, `self` - replies directed to you."
 217     )
 218   end
 219
 220   defp only_media_param do
 221     Operation.parameter(
 222       :only_media,
 223       :query,
 224       %Schema{allOf: [BooleanLike], default: false},
 225       "Show only statuses with media attached?"
 226     )
 227   end
 228
 229   defp remote_param do
 230     Operation.parameter(
 231       :remote,
 232       :query,
 233       %Schema{allOf: [BooleanLike], default: false},
 234       "Show only remote statuses?"
 235     )
 236   end
 237 end