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