First
[anni] / lib / pleroma / web / api_spec / operations / timeline_operation.ex
1 # Pleroma: A lightweight social networking server
2 # Copyright © 2017-2022 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         remote_param(),
29         only_media_param(),
30         with_muted_param(),
31         exclude_visibilities_param(),
32         reply_visibility_param() | pagination_params()
33       ],
34       operationId: "TimelineController.home",
35       responses: %{
36         200 => Operation.response("Array of Status", "application/json", array_of_statuses())
37       }
38     }
39   end
40
41   def direct_operation do
42     %Operation{
43       tags: ["Timelines"],
44       summary: "Direct timeline",
45       description:
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",
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         instance_param(),
64         only_media_param(),
65         remote_param(),
66         with_muted_param(),
67         exclude_visibilities_param(),
68         reply_visibility_param() | pagination_params()
69       ],
70       operationId: "TimelineController.public",
71       responses: %{
72         200 => Operation.response("Array of Status", "application/json", array_of_statuses()),
73         401 => Operation.response("Error", "application/json", ApiError)
74       }
75     }
76   end
77
78   def hashtag_operation do
79     %Operation{
80       tags: ["Timelines"],
81       summary: "Hashtag timeline",
82       description: "View public statuses containing the given hashtag",
83       security: [%{"oAuth" => ["read:statuses"]}],
84       parameters: [
85         Operation.parameter(
86           :tag,
87           :path,
88           %Schema{type: :string},
89           "Content of a #hashtag, not including # symbol.",
90           required: true
91         ),
92         Operation.parameter(
93           :any,
94           :query,
95           %Schema{type: :array, items: %Schema{type: :string}},
96           "Statuses that also includes any of these tags"
97         ),
98         Operation.parameter(
99           :all,
100           :query,
101           %Schema{type: :array, items: %Schema{type: :string}},
102           "Statuses that also includes all of these tags"
103         ),
104         Operation.parameter(
105           :none,
106           :query,
107           %Schema{type: :array, items: %Schema{type: :string}},
108           "Statuses that do not include these tags"
109         ),
110         local_param(),
111         only_media_param(),
112         remote_param(),
113         with_muted_param(),
114         exclude_visibilities_param() | pagination_params()
115       ],
116       operationId: "TimelineController.hashtag",
117       responses: %{
118         200 => Operation.response("Array of Status", "application/json", array_of_statuses()),
119         401 => Operation.response("Error", "application/json", ApiError)
120       }
121     }
122   end
123
124   def list_operation do
125     %Operation{
126       tags: ["Timelines"],
127       summary: "List timeline",
128       description: "View statuses in the given list timeline",
129       security: [%{"oAuth" => ["read:lists"]}],
130       parameters: [
131         Operation.parameter(
132           :list_id,
133           :path,
134           %Schema{type: :string},
135           "Local ID of the list in the database",
136           required: true
137         ),
138         with_muted_param(),
139         local_param(),
140         remote_param(),
141         only_media_param(),
142         exclude_visibilities_param() | pagination_params()
143       ],
144       operationId: "TimelineController.list",
145       responses: %{
146         200 => Operation.response("Array of Status", "application/json", array_of_statuses())
147       }
148     }
149   end
150
151   defp array_of_statuses do
152     %Schema{
153       title: "ArrayOfStatuses",
154       type: :array,
155       items: Status,
156       example: [Status.schema().example]
157     }
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 instance_param do
170     Operation.parameter(
171       :instance,
172       :query,
173       %Schema{type: :string},
174       "Show only statuses from the given domain"
175     )
176   end
177
178   defp with_muted_param do
179     Operation.parameter(:with_muted, :query, BooleanLike, "Include activities by muted users")
180   end
181
182   defp exclude_visibilities_param do
183     Operation.parameter(
184       :exclude_visibilities,
185       :query,
186       %Schema{type: :array, items: VisibilityScope},
187       "Exclude the statuses with the given visibilities"
188     )
189   end
190
191   defp reply_visibility_param do
192     Operation.parameter(
193       :reply_visibility,
194       :query,
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."
197     )
198   end
199
200   defp only_media_param do
201     Operation.parameter(
202       :only_media,
203       :query,
204       %Schema{allOf: [BooleanLike], default: false},
205       "Show only statuses with media attached?"
206     )
207   end
208
209   defp remote_param do
210     Operation.parameter(
211       :remote,
212       :query,
213       %Schema{allOf: [BooleanLike], default: false},
214       "Show only remote statuses?"
215     )
216   end
217 end