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