1 # Pleroma: A lightweight social networking server
2 # Copyright © 2017-2022 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) or [chats](#tag/Chats).",
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 hashtag_operation do
81 summary: "Hashtag timeline",
82 description: "View public statuses containing the given hashtag",
83 security: [%{"oAuth" => ["read:statuses"]}],
88 %Schema{type: :string},
89 "Content of a #hashtag, not including # symbol.",
95 %Schema{type: :array, items: %Schema{type: :string}},
96 "Statuses that also includes any of these tags"
101 %Schema{type: :array, items: %Schema{type: :string}},
102 "Statuses that also includes all of these tags"
107 %Schema{type: :array, items: %Schema{type: :string}},
108 "Statuses that do not include these tags"
114 exclude_visibilities_param() | pagination_params()
116 operationId: "TimelineController.hashtag",
118 200 => Operation.response("Array of Status", "application/json", array_of_statuses()),
119 401 => Operation.response("Error", "application/json", ApiError)
124 def list_operation do
127 summary: "List timeline",
128 description: "View statuses in the given list timeline",
129 security: [%{"oAuth" => ["read:lists"]}],
134 %Schema{type: :string},
135 "Local ID of the list in the database",
142 exclude_visibilities_param() | pagination_params()
144 operationId: "TimelineController.list",
146 200 => Operation.response("Array of Status", "application/json", array_of_statuses())
151 defp array_of_statuses do
153 title: "ArrayOfStatuses",
156 example: [Status.schema().example]
164 %Schema{allOf: [BooleanLike], default: false},
165 "Show only local statuses?"
169 defp instance_param do
173 %Schema{type: :string},
174 "Show only statuses from the given domain"
178 defp with_muted_param do
179 Operation.parameter(:with_muted, :query, BooleanLike, "Include activities by muted users")
182 defp exclude_visibilities_param do
184 :exclude_visibilities,
186 %Schema{type: :array, items: VisibilityScope},
187 "Exclude the statuses with the given visibilities"
191 defp reply_visibility_param do
195 %Schema{type: :string, enum: ["following", "self"]},
196 "Filter replies. Possible values: without parameter (default) shows all replies, `following` - replies directed to you or users you follow, `self` - replies directed to you."
200 defp only_media_param do
204 %Schema{allOf: [BooleanLike], default: false},
205 "Show only statuses with media attached?"
213 %Schema{allOf: [BooleanLike], default: false},
214 "Show only remote statuses?"