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-2020 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(),
  31         with_relationships_param() | pagination_params()
  32       ],
  33       operationId: "TimelineController.home",
  34       responses: %{
  35         200 => Operation.response("Array of Status", "application/json", array_of_statuses())
  36       }
  37     }
  38   end
  39
  40   def direct_operation do
  41     %Operation{
  42       tags: ["Timelines"],
  43       summary: "Direct timeline",
  44       description:
  45         "View statuses with a “direct” privacy, from your account or in your notifications",
  46       deprecated: true,
  47       parameters: 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         only_media_param(),
  64         with_muted_param(),
  65         exclude_visibilities_param(),
  66         reply_visibility_param(),
  67         with_relationships_param() | pagination_params()
  68       ],
  69       operationId: "TimelineController.public",
  70       responses: %{
  71         200 => Operation.response("Array of Status", "application/json", array_of_statuses()),
  72         401 => Operation.response("Error", "application/json", ApiError)
  73       }
  74     }
  75   end
  76
  77   def hashtag_operation do
  78     %Operation{
  79       tags: ["Timelines"],
  80       summary: "Hashtag timeline",
  81       description: "View public statuses containing the given hashtag",
  82       security: [%{"oAuth" => ["read:statuses"]}],
  83       parameters: [
  84         Operation.parameter(
  85           :tag,
  86           :path,
  87           %Schema{type: :string},
  88           "Content of a #hashtag, not including # symbol.",
  89           required: true
  90         ),
  91         Operation.parameter(
  92           :any,
  93           :query,
  94           %Schema{type: :array, items: %Schema{type: :string}},
  95           "Statuses that also includes any of these tags"
  96         ),
  97         Operation.parameter(
  98           :all,
  99           :query,
 100           %Schema{type: :array, items: %Schema{type: :string}},
 101           "Statuses that also includes all of these tags"
 102         ),
 103         Operation.parameter(
 104           :none,
 105           :query,
 106           %Schema{type: :array, items: %Schema{type: :string}},
 107           "Statuses that do not include these tags"
 108         ),
 109         local_param(),
 110         only_media_param(),
 111         with_muted_param(),
 112         exclude_visibilities_param(),
 113         with_relationships_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(),
 138         with_relationships_param() | pagination_params()
 139       ],
 140       operationId: "TimelineController.list",
 141       responses: %{
 142         200 => Operation.response("Array of Status", "application/json", array_of_statuses())
 143       }
 144     }
 145   end
 146
 147   defp array_of_statuses do
 148     %Schema{
 149       title: "ArrayOfStatuses",
 150       type: :array,
 151       items: Status,
 152       example: [Status.schema().example]
 153     }
 154   end
 155
 156   defp with_relationships_param do
 157     Operation.parameter(:with_relationships, :query, BooleanLike, "Include relationships")
 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 with_muted_param do
 170     Operation.parameter(:with_muted, :query, BooleanLike, "Includeactivities by muted users")
 171   end
 172
 173   defp exclude_visibilities_param do
 174     Operation.parameter(
 175       :exclude_visibilities,
 176       :query,
 177       %Schema{type: :array, items: VisibilityScope},
 178       "Exclude the statuses with the given visibilities"
 179     )
 180   end
 181
 182   defp reply_visibility_param do
 183     Operation.parameter(
 184       :reply_visibility,
 185       :query,
 186       %Schema{type: :string, enum: ["following", "self"]},
 187       "Filter replies. Possible values: without parameter (default) shows all replies, `following` - replies directed to you or users you follow, `self` - replies directed to you."
 188     )
 189   end
 190
 191   defp only_media_param do
 192     Operation.parameter(
 193       :only_media,
 194       :query,
 195       %Schema{allOf: [BooleanLike], default: false},
 196       "Show only statuses with media attached?"
 197     )
 198   end
 199 end