e5bf18d4d199d6b6f4bdf4f79275e2664b6bd30f
[akkoma] / lib / pleroma / web / api_spec / operations / timeline_operation.ex
1 # Pleroma: A lightweight social networking server
2 # Copyright © 2017-2021 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 only_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” privacy, from your account or in your notifications",
47 deprecated: true,
48 parameters: [with_muted_param() | pagination_params()],
49 security: [%{"oAuth" => ["read:statuses"]}],
50 operationId: "TimelineController.direct",
51 responses: %{
52 200 => Operation.response("Array of Status", "application/json", array_of_statuses())
53 }
54 }
55 end
56
57 def public_operation do
58 %Operation{
59 tags: ["Timelines"],
60 summary: "Public timeline",
61 security: [%{"oAuth" => ["read:statuses"]}],
62 parameters: [
63 local_param(),
64 instance_param(),
65 only_media_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 with_muted_param(),
113 exclude_visibilities_param() | pagination_params()
114 ],
115 operationId: "TimelineController.hashtag",
116 responses: %{
117 200 => Operation.response("Array of Status", "application/json", array_of_statuses())
118 }
119 }
120 end
121
122 def list_operation do
123 %Operation{
124 tags: ["Timelines"],
125 summary: "List timeline",
126 description: "View statuses in the given list timeline",
127 security: [%{"oAuth" => ["read:lists"]}],
128 parameters: [
129 Operation.parameter(
130 :list_id,
131 :path,
132 %Schema{type: :string},
133 "Local ID of the list in the database",
134 required: true
135 ),
136 with_muted_param(),
137 local_param(),
138 only_remote_param(),
139 only_media_param(),
140 exclude_visibilities_param() | pagination_params()
141 ],
142 operationId: "TimelineController.list",
143 responses: %{
144 200 => Operation.response("Array of Status", "application/json", array_of_statuses())
145 }
146 }
147 end
148
149 defp array_of_statuses do
150 %Schema{
151 title: "ArrayOfStatuses",
152 type: :array,
153 items: Status,
154 example: [Status.schema().example]
155 }
156 end
157
158 defp local_param do
159 Operation.parameter(
160 :local,
161 :query,
162 %Schema{allOf: [BooleanLike], default: false},
163 "Show only local statuses?"
164 )
165 end
166
167 defp instance_param do
168 Operation.parameter(
169 :instance,
170 :query,
171 %Schema{type: :string},
172 "Show only statuses from the given domain"
173 )
174 end
175
176 defp with_muted_param do
177 Operation.parameter(:with_muted, :query, BooleanLike, "Include activities by muted users")
178 end
179
180 defp exclude_visibilities_param do
181 Operation.parameter(
182 :exclude_visibilities,
183 :query,
184 %Schema{type: :array, items: VisibilityScope},
185 "Exclude the statuses with the given visibilities"
186 )
187 end
188
189 defp reply_visibility_param do
190 Operation.parameter(
191 :reply_visibility,
192 :query,
193 %Schema{type: :string, enum: ["following", "self"]},
194 "Filter replies. Possible values: without parameter (default) shows all replies, `following` - replies directed to you or users you follow, `self` - replies directed to you."
195 )
196 end
197
198 defp only_media_param do
199 Operation.parameter(
200 :only_media,
201 :query,
202 %Schema{allOf: [BooleanLike], default: false},
203 "Show only statuses with media attached?"
204 )
205 end
206
207 defp only_remote_param do
208 Operation.parameter(
209 :only_remote,
210 :query,
211 %Schema{allOf: [BooleanLike], default: false},
212 "Show only remote statuses?"
213 )
214 end
215 end