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),
74 404 => Operation.response("Error", "application/json", ApiError)
79 def bubble_operation do
82 summary: "Bubble timeline",
83 security: [%{"oAuth" => ["read:statuses"]}],
88 exclude_visibilities_param(),
89 reply_visibility_param() | pagination_params()
91 operationId: "TimelineController.bubble",
93 200 => Operation.response("Array of Status", "application/json", array_of_statuses()),
94 401 => Operation.response("Error", "application/json", ApiError)
99 def hashtag_operation do
102 summary: "Hashtag timeline",
103 description: "View public statuses containing the given hashtag",
104 security: [%{"oAuth" => ["read:statuses"]}],
109 %Schema{type: :string},
110 "Content of a #hashtag, not including # symbol.",
116 %Schema{type: :array, items: %Schema{type: :string}},
117 "Statuses that also includes any of these tags"
122 %Schema{type: :array, items: %Schema{type: :string}},
123 "Statuses that also includes all of these tags"
128 %Schema{type: :array, items: %Schema{type: :string}},
129 "Statuses that do not include these tags"
135 exclude_visibilities_param() | pagination_params()
137 operationId: "TimelineController.hashtag",
139 200 => Operation.response("Array of Status", "application/json", array_of_statuses()),
140 401 => Operation.response("Error", "application/json", ApiError)
145 def list_operation do
148 summary: "List timeline",
149 description: "View statuses in the given list timeline",
150 security: [%{"oAuth" => ["read:lists"]}],
155 %Schema{type: :string},
156 "Local ID of the list in the database",
163 exclude_visibilities_param() | pagination_params()
165 operationId: "TimelineController.list",
167 200 => Operation.response("Array of Status", "application/json", array_of_statuses())
172 defp array_of_statuses do
174 title: "ArrayOfStatuses",
177 example: [Status.schema().example]
185 %Schema{allOf: [BooleanLike], default: false},
186 "Show only local statuses?"
190 defp instance_param do
194 %Schema{type: :string},
195 "Show only statuses from the given domain"
199 defp with_muted_param do
200 Operation.parameter(:with_muted, :query, BooleanLike, "Include activities by muted users")
203 defp exclude_visibilities_param do
205 :exclude_visibilities,
207 %Schema{type: :array, items: VisibilityScope},
208 "Exclude the statuses with the given visibilities"
212 defp reply_visibility_param do
216 %Schema{type: :string, enum: ["following", "self"]},
217 "Filter replies. Possible values: without parameter (default) shows all replies, `following` - replies directed to you or users you follow, `self` - replies directed to you."
221 defp only_media_param do
225 %Schema{allOf: [BooleanLike], default: false},
226 "Show only statuses with media attached?"
234 %Schema{allOf: [BooleanLike], default: false},
235 "Show only remote statuses?"