1 # Pleroma: A lightweight social networking server
2 # Copyright © 2017-2020 Pleroma Authors <https://pleroma.social/>
3 # SPDX-License-Identifier: AGPL-3.0-only
5 defmodule Pleroma.Web.ApiSpec.StatusOperation do
6 alias OpenApiSpex.Operation
7 alias OpenApiSpex.Schema
8 alias Pleroma.Web.ApiSpec.AccountOperation
9 alias Pleroma.Web.ApiSpec.Schemas.ApiError
10 alias Pleroma.Web.ApiSpec.Schemas.BooleanLike
11 alias Pleroma.Web.ApiSpec.Schemas.FlakeID
12 alias Pleroma.Web.ApiSpec.Schemas.ScheduledStatus
13 alias Pleroma.Web.ApiSpec.Schemas.Status
14 alias Pleroma.Web.ApiSpec.Schemas.VisibilityScope
16 import Pleroma.Web.ApiSpec.Helpers
18 def open_api_operation(action) do
19 operation = String.to_existing_atom("#{action}_operation")
20 apply(__MODULE__, operation, [])
23 def index_operation do
26 summary: "Get multiple statuses by IDs",
27 security: [%{"oAuth" => ["read:statuses"]}],
32 %Schema{type: :array, items: FlakeID},
36 operationId: "StatusController.index",
38 200 => Operation.response("Array of Status", "application/json", array_of_statuses())
43 def create_operation do
46 summary: "Publish new status",
47 security: [%{"oAuth" => ["write:statuses"]}],
48 description: "Post a new status",
49 operationId: "StatusController.create",
50 requestBody: request_body("Parameters", create_request(), required: true),
54 "Status. When `scheduled_at` is present, ScheduledStatus is returned instead",
56 %Schema{oneOf: [Status, ScheduledStatus]}
58 422 => Operation.response("Bad Request", "application/json", ApiError)
66 summary: "View specific status",
67 description: "View information about a status",
68 operationId: "StatusController.show",
69 security: [%{"oAuth" => ["read:statuses"]}],
70 parameters: [id_param()],
72 200 => status_response(),
73 404 => Operation.response("Not Found", "application/json", ApiError)
78 def delete_operation do
81 summary: "Delete status",
82 security: [%{"oAuth" => ["write:statuses"]}],
83 description: "Delete one of your own statuses",
84 operationId: "StatusController.delete",
85 parameters: [id_param()],
87 200 => empty_object_response(),
88 403 => Operation.response("Forbidden", "application/json", ApiError),
89 404 => Operation.response("Not Found", "application/json", ApiError)
94 def reblog_operation do
98 security: [%{"oAuth" => ["write:statuses"]}],
99 description: "Share a status",
100 operationId: "StatusController.reblog",
101 parameters: [id_param()],
103 request_body("Parameters", %Schema{
106 visibility: %Schema{allOf: [VisibilityScope], default: "public"}
110 200 => status_response(),
111 404 => Operation.response("Not Found", "application/json", ApiError)
116 def unreblog_operation do
119 summary: "Undo boost",
120 security: [%{"oAuth" => ["write:statuses"]}],
121 description: "Undo a reshare of a status",
122 operationId: "StatusController.unreblog",
123 parameters: [id_param()],
125 200 => status_response(),
126 404 => Operation.response("Not Found", "application/json", ApiError)
131 def favourite_operation do
134 summary: "Favourite",
135 security: [%{"oAuth" => ["write:favourites"]}],
136 description: "Add a status to your favourites list",
137 operationId: "StatusController.favourite",
138 parameters: [id_param()],
140 200 => status_response(),
141 404 => Operation.response("Not Found", "application/json", ApiError)
146 def unfavourite_operation do
149 summary: "Undo favourite",
150 security: [%{"oAuth" => ["write:favourites"]}],
151 description: "Remove a status from your favourites list",
152 operationId: "StatusController.unfavourite",
153 parameters: [id_param()],
155 200 => status_response(),
156 404 => Operation.response("Not Found", "application/json", ApiError)
164 summary: "Pin to profile",
165 security: [%{"oAuth" => ["write:accounts"]}],
166 description: "Feature one of your own public statuses at the top of your profile",
167 operationId: "StatusController.pin",
168 parameters: [id_param()],
170 200 => status_response(),
171 400 => Operation.response("Error", "application/json", ApiError)
176 def unpin_operation do
179 summary: "Unpin to profile",
180 security: [%{"oAuth" => ["write:accounts"]}],
181 description: "Unfeature a status from the top of your profile",
182 operationId: "StatusController.unpin",
183 parameters: [id_param()],
185 200 => status_response(),
186 400 => Operation.response("Error", "application/json", ApiError)
191 def bookmark_operation do
195 security: [%{"oAuth" => ["write:bookmarks"]}],
196 description: "Privately bookmark a status",
197 operationId: "StatusController.bookmark",
198 parameters: [id_param()],
200 200 => status_response()
205 def unbookmark_operation do
208 summary: "Undo bookmark",
209 security: [%{"oAuth" => ["write:bookmarks"]}],
210 description: "Remove a status from your private bookmarks",
211 operationId: "StatusController.unbookmark",
212 parameters: [id_param()],
214 200 => status_response()
219 def mute_conversation_operation do
222 summary: "Mute conversation",
223 security: [%{"oAuth" => ["write:mutes"]}],
225 "Do not receive notifications for the thread that this status is part of. Must be a thread in which you are a participant.",
226 operationId: "StatusController.mute_conversation",
227 parameters: [id_param()],
229 200 => status_response(),
230 400 => Operation.response("Error", "application/json", ApiError)
235 def unmute_conversation_operation do
238 summary: "Unmute conversation",
239 security: [%{"oAuth" => ["write:mutes"]}],
241 "Start receiving notifications again for the thread that this status is part of",
242 operationId: "StatusController.unmute_conversation",
243 parameters: [id_param()],
245 200 => status_response(),
246 400 => Operation.response("Error", "application/json", ApiError)
251 def card_operation do
255 summary: "Preview card",
256 description: "Deprecated in favor of card property inlined on Status entity",
257 operationId: "StatusController.card",
258 parameters: [id_param()],
259 security: [%{"oAuth" => ["read:statuses"]}],
262 Operation.response("Card", "application/json", %Schema{
266 type: %Schema{type: :string, enum: ["link", "photo", "video", "rich"]},
267 provider_name: %Schema{type: :string, nullable: true},
268 provider_url: %Schema{type: :string, format: :uri},
269 url: %Schema{type: :string, format: :uri},
270 image: %Schema{type: :string, nullable: true, format: :uri},
271 title: %Schema{type: :string},
272 description: %Schema{type: :string}
279 def favourited_by_operation do
282 summary: "Favourited by",
283 description: "View who favourited a given status",
284 operationId: "StatusController.favourited_by",
285 security: [%{"oAuth" => ["read:accounts"]}],
286 parameters: [id_param()],
292 AccountOperation.array_of_accounts()
294 404 => Operation.response("Not Found", "application/json", ApiError)
299 def reblogged_by_operation do
302 summary: "Boosted by",
303 description: "View who boosted a given status",
304 operationId: "StatusController.reblogged_by",
305 security: [%{"oAuth" => ["read:accounts"]}],
306 parameters: [id_param()],
312 AccountOperation.array_of_accounts()
314 404 => Operation.response("Not Found", "application/json", ApiError)
319 def context_operation do
322 summary: "Parent and child statuses",
323 description: "View statuses above and below this status in the thread",
324 operationId: "StatusController.context",
325 security: [%{"oAuth" => ["read:statuses"]}],
326 parameters: [id_param()],
328 200 => Operation.response("Context", "application/json", context())
333 def favourites_operation do
336 summary: "Favourited statuses",
337 description: "Statuses the user has favourited",
338 operationId: "StatusController.favourites",
339 parameters: pagination_params(),
340 security: [%{"oAuth" => ["read:favourites"]}],
342 200 => Operation.response("Array of Statuses", "application/json", array_of_statuses())
347 def bookmarks_operation do
350 summary: "Bookmarked statuses",
351 description: "Statuses the user has bookmarked",
352 operationId: "StatusController.bookmarks",
354 Operation.parameter(:with_relationships, :query, BooleanLike, "Include relationships")
355 | pagination_params()
357 security: [%{"oAuth" => ["read:bookmarks"]}],
359 200 => Operation.response("Array of Statuses", "application/json", array_of_statuses())
364 defp array_of_statuses do
365 %Schema{type: :array, items: Status, example: [Status.schema().example]}
368 defp create_request do
370 title: "StatusCreateRequest",
376 "Text content of the status. If `media_ids` is provided, this becomes optional. Attaching a `poll` is optional while `status` is provided."
380 items: %Schema{type: :string},
382 "Array of Attachment ids to be attached as media. If provided, `status` becomes optional, and `poll` cannot be used."
386 required: [:options],
390 items: %Schema{type: :string},
392 "Array of possible answers. If provided, `media_ids` cannot be used, and `poll[expires_in]` must be provided."
397 "Duration the poll should be open, in seconds. If provided, `media_ids` cannot be used, and `poll[options]` must be provided."
399 multiple: %Schema{type: :boolean, description: "Allow multiple choices?"},
400 hide_totals: %Schema{
402 description: "Hide vote counts until the poll ends?"
406 in_reply_to_id: %Schema{
408 description: "ID of the status being replied to, if status is a reply"
412 description: "Mark status and attached media as sensitive?"
414 spoiler_text: %Schema{
417 "Text to be shown as a warning or subject before the actual content. Statuses are generally collapsed behind this field."
419 scheduled_at: %Schema{
421 format: :"date-time",
424 "ISO 8601 Datetime at which to schedule a status. Providing this paramter will cause ScheduledStatus to be returned instead of Status. Must be at least 5 minutes in the future."
426 language: %Schema{type: :string, description: "ISO 639 language code for this status."},
427 # Pleroma-specific properties:
431 "If set to `true` the post won't be actually posted, but the status entitiy would still be rendered back. This could be useful for previewing rich text/custom emoji, for example"
433 content_type: %Schema{
436 "The MIME type of the status, it is transformed into HTML by the backend. You can get the list of the supported MIME types with the nodeinfo endpoint."
440 items: %Schema{type: :string},
442 "A list of nicknames (like `lain@soykaf.club` or `lain` on the local server) that will be used to determine who is going to be addressed by this post. Using this will disable the implicit addressing by mentioned names in the `status` body, only the people in the `to` list will be addressed. The normal rules for for post visibility are not affected by this and will still apply"
447 %Schema{type: :string, description: "`list:LIST_ID`", example: "LIST:123"}
450 "Visibility of the posted status. Besides standard MastoAPI values (`direct`, `private`, `unlisted` or `public`) it can be used to address a List by setting it to `list:LIST_ID`"
455 "The number of seconds the posted activity should expire in. When a posted activity expires it will be deleted from the server, and a delete request for it will be federated. This needs to be longer than an hour."
457 in_reply_to_conversation_id: %Schema{
460 "Will reply to a given conversation, addressing only the people who are part of the recipient set of that conversation. Sets the visibility to `direct`."
464 "status" => "What time is it?",
465 "sensitive" => "false",
467 "options" => ["Cofe", "Adventure"],
475 Operation.parameter(:id, :path, FlakeID, "Status ID",
476 example: "9umDrYheeY451cQnEe",
481 defp status_response do
482 Operation.response("Status", "application/json", Status)
487 title: "StatusContext",
489 "Represents the tree around a given status. Used for reconstructing threads of statuses.",
491 required: [:ancestors, :descendants],
493 ancestors: array_of_statuses(),
494 descendants: array_of_statuses()
497 "ancestors" => [Status.schema().example],
498 "descendants" => [Status.schema().example]