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