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