1 # Pleroma: A lightweight social networking server
2 # Copyright © 2017-2021 Pleroma Authors <https://pleroma.social/>
3 # SPDX-License-Identifier: AGPL-3.0-only
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
13 import Pleroma.Web.ApiSpec.Helpers
15 def open_api_operation(action) do
16 operation = String.to_existing_atom("#{action}_operation")
17 apply(__MODULE__, operation, [])
23 summary: "Home timeline",
24 description: "View statuses from followed users",
25 security: [%{"oAuth" => ["read:statuses"]}],
31 exclude_visibilities_param(),
32 reply_visibility_param() | pagination_params()
34 operationId: "TimelineController.home",
36 200 => Operation.response("Array of Status", "application/json", array_of_statuses())
41 def direct_operation do
44 summary: "Direct timeline",
46 "View statuses with a “direct” scope addressed to the account. Using this endpoint is discouraged, please use [conversations](#tag/Conversations).",
47 parameters: [with_muted_param() | pagination_params()],
48 security: [%{"oAuth" => ["read:statuses"]}],
49 operationId: "TimelineController.direct",
51 200 => Operation.response("Array of Status", "application/json", array_of_statuses())
56 def public_operation do
59 summary: "Public timeline",
60 security: [%{"oAuth" => ["read:statuses"]}],
67 exclude_visibilities_param(),
68 reply_visibility_param() | pagination_params()
70 operationId: "TimelineController.public",
72 200 => Operation.response("Array of Status", "application/json", array_of_statuses()),
73 401 => Operation.response("Error", "application/json", ApiError)
78 def bubble_operation do
81 summary: "Bubble timeline",
82 security: [%{"oAuth" => ["read:statuses"]}],
87 exclude_visibilities_param(),
88 reply_visibility_param() | pagination_params()
90 operationId: "TimelineController.bubble",
92 200 => Operation.response("Array of Status", "application/json", array_of_statuses()),
93 401 => Operation.response("Error", "application/json", ApiError)
98 def hashtag_operation do
101 summary: "Hashtag timeline",
102 description: "View public statuses containing the given hashtag",
103 security: [%{"oAuth" => ["read:statuses"]}],
108 %Schema{type: :string},
109 "Content of a #hashtag, not including # symbol.",
115 %Schema{type: :array, items: %Schema{type: :string}},
116 "Statuses that also includes any of these tags"
121 %Schema{type: :array, items: %Schema{type: :string}},
122 "Statuses that also includes all of these tags"
127 %Schema{type: :array, items: %Schema{type: :string}},
128 "Statuses that do not include these tags"
134 exclude_visibilities_param() | pagination_params()
136 operationId: "TimelineController.hashtag",
138 200 => Operation.response("Array of Status", "application/json", array_of_statuses()),
139 401 => Operation.response("Error", "application/json", ApiError)
144 def list_operation do
147 summary: "List timeline",
148 description: "View statuses in the given list timeline",
149 security: [%{"oAuth" => ["read:lists"]}],
154 %Schema{type: :string},
155 "Local ID of the list in the database",
162 exclude_visibilities_param() | pagination_params()
164 operationId: "TimelineController.list",
166 200 => Operation.response("Array of Status", "application/json", array_of_statuses())
171 defp array_of_statuses do
173 title: "ArrayOfStatuses",
176 example: [Status.schema().example]
184 %Schema{allOf: [BooleanLike], default: false},
185 "Show only local statuses?"
189 defp instance_param do
193 %Schema{type: :string},
194 "Show only statuses from the given domain"
198 defp with_muted_param do
199 Operation.parameter(:with_muted, :query, BooleanLike, "Include activities by muted users")
202 defp exclude_visibilities_param do
204 :exclude_visibilities,
206 %Schema{type: :array, items: VisibilityScope},
207 "Exclude the statuses with the given visibilities"
211 defp reply_visibility_param do
215 %Schema{type: :string, enum: ["following", "self"]},
216 "Filter replies. Possible values: without parameter (default) shows all replies, `following` - replies directed to you or users you follow, `self` - replies directed to you."
220 defp only_media_param do
224 %Schema{allOf: [BooleanLike], default: false},
225 "Show only statuses with media attached?"
233 %Schema{allOf: [BooleanLike], default: false},
234 "Show only remote statuses?"