total rebase
[anni] / lib / pleroma / web / api_spec / operations / instance_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.InstanceOperation do
6   alias OpenApiSpex.Operation
7   alias OpenApiSpex.Schema
8
9   def open_api_operation(action) do
10     operation = String.to_existing_atom("#{action}_operation")
11     apply(__MODULE__, operation, [])
12   end
13
14   def show_operation do
15     %Operation{
16       tags: ["Instance misc"],
17       summary: "Retrieve instance information",
18       description: "Information about the server",
19       operationId: "InstanceController.show",
20       responses: %{
21         200 => Operation.response("Instance", "application/json", instance())
22       }
23     }
24   end
25
26   def show2_operation do
27     %Operation{
28       tags: ["Instance misc"],
29       summary: "Retrieve instance information",
30       description: "Information about the server",
31       operationId: "InstanceController.show2",
32       responses: %{
33         200 => Operation.response("Instance", "application/json", instance2())
34       }
35     }
36   end
37
38   def peers_operation do
39     %Operation{
40       tags: ["Instance misc"],
41       summary: "Retrieve list of known instances",
42       operationId: "InstanceController.peers",
43       responses: %{
44         200 => Operation.response("Array of domains", "application/json", array_of_domains())
45       }
46     }
47   end
48
49   defp instance do
50     %Schema{
51       type: :object,
52       properties: %{
53         accounts: %Schema{
54           type: :object,
55           properties: %{
56             max_featured_tags: %Schema{
57               type: :integer,
58               description: "The maximum number of featured tags allowed for each account."
59             }
60           }
61         },
62         uri: %Schema{type: :string, description: "The domain name of the instance"},
63         title: %Schema{type: :string, description: "The title of the website"},
64         description: %Schema{
65           type: :string,
66           description: "Admin-defined description of the Pleroma site"
67         },
68         version: %Schema{
69           type: :string,
70           description: "The version of Pleroma installed on the instance"
71         },
72         email: %Schema{
73           type: :string,
74           description: "An email that may be contacted for any inquiries",
75           format: :email
76         },
77         urls: %Schema{
78           type: :object,
79           description: "URLs of interest for clients apps",
80           properties: %{
81             streaming_api: %Schema{
82               type: :string,
83               description: "Websockets address for push streaming"
84             }
85           }
86         },
87         stats: %Schema{
88           type: :object,
89           description: "Statistics about how much information the instance contains",
90           properties: %{
91             user_count: %Schema{
92               type: :integer,
93               description: "Users registered on this instance"
94             },
95             status_count: %Schema{
96               type: :integer,
97               description: "Statuses authored by users on instance"
98             },
99             domain_count: %Schema{
100               type: :integer,
101               description: "Domains federated with this instance"
102             }
103           }
104         },
105         thumbnail: %Schema{
106           type: :string,
107           description: "Banner image for the website",
108           nullable: true
109         },
110         languages: %Schema{
111           type: :array,
112           items: %Schema{type: :string},
113           description: "Primary languages of the website and its staff"
114         },
115         registrations: %Schema{type: :boolean, description: "Whether registrations are enabled"},
116         # Extra (not present in Mastodon):
117         max_toot_chars: %Schema{
118           type: :integer,
119           description: ": Posts character limit (CW/Subject included in the counter)"
120         },
121         poll_limits: %Schema{
122           type: :object,
123           description: "A map with poll limits for local polls",
124           properties: %{
125             max_options: %Schema{
126               type: :integer,
127               description: "Maximum number of options."
128             },
129             max_option_chars: %Schema{
130               type: :integer,
131               description: "Maximum number of characters per option."
132             },
133             min_expiration: %Schema{
134               type: :integer,
135               description: "Minimum expiration time (in seconds)."
136             },
137             max_expiration: %Schema{
138               type: :integer,
139               description: "Maximum expiration time (in seconds)."
140             }
141           }
142         },
143         upload_limit: %Schema{
144           type: :integer,
145           description: "File size limit of uploads (except for avatar, background, banner)"
146         },
147         avatar_upload_limit: %Schema{type: :integer, description: "The title of the website"},
148         background_upload_limit: %Schema{type: :integer, description: "The title of the website"},
149         banner_upload_limit: %Schema{type: :integer, description: "The title of the website"},
150         background_image: %Schema{
151           type: :string,
152           format: :uri,
153           description: "The background image for the website"
154         }
155       },
156       example: %{
157         "avatar_upload_limit" => 2_000_000,
158         "background_upload_limit" => 4_000_000,
159         "background_image" => "/static/image.png",
160         "banner_upload_limit" => 4_000_000,
161         "description" => "Pleroma: An efficient and flexible fediverse server",
162         "email" => "lain@lain.com",
163         "languages" => ["en"],
164         "max_toot_chars" => 5000,
165         "poll_limits" => %{
166           "max_expiration" => 31_536_000,
167           "max_option_chars" => 200,
168           "max_options" => 20,
169           "min_expiration" => 0
170         },
171         "registrations" => false,
172         "stats" => %{
173           "domain_count" => 2996,
174           "status_count" => 15_802,
175           "user_count" => 5
176         },
177         "thumbnail" => "https://lain.com/instance/thumbnail.jpeg",
178         "title" => "lain.com",
179         "upload_limit" => 16_000_000,
180         "uri" => "https://lain.com",
181         "urls" => %{
182           "streaming_api" => "wss://lain.com"
183         },
184         "version" => "2.7.2 (compatible; Pleroma 2.0.50-536-g25eec6d7-develop)"
185       }
186     }
187   end
188
189   defp instance2 do
190     %Schema{
191       type: :object,
192       properties: %{
193         domain: %Schema{type: :string, description: "The domain name of the instance"},
194         title: %Schema{type: :string, description: "The title of the website"},
195         version: %Schema{
196           type: :string,
197           description: "The version of Pleroma installed on the instance"
198         },
199         source_url: %Schema{
200           type: :string,
201           description: "The version of Pleroma installed on the instance"
202         },
203         description: %Schema{
204           type: :string,
205           description: "Admin-defined description of the Pleroma site"
206         },
207         usage: %Schema{
208           type: :object,
209           description: "Instance usage statistics",
210           properties: %{
211             users: %Schema{
212               type: :object,
213               description: "User count statistics",
214               properties: %{
215                 active_month: %Schema{
216                   type: :integer,
217                   description: "Monthly active users"
218                 }
219               }
220             }
221           }
222         },
223         email: %Schema{
224           type: :string,
225           description: "An email that may be contacted for any inquiries",
226           format: :email
227         },
228         urls: %Schema{
229           type: :object,
230           description: "URLs of interest for clients apps",
231           properties: %{}
232         },
233         stats: %Schema{
234           type: :object,
235           description: "Statistics about how much information the instance contains",
236           properties: %{
237             user_count: %Schema{
238               type: :integer,
239               description: "Users registered on this instance"
240             },
241             status_count: %Schema{
242               type: :integer,
243               description: "Statuses authored by users on instance"
244             },
245             domain_count: %Schema{
246               type: :integer,
247               description: "Domains federated with this instance"
248             }
249           }
250         },
251         thumbnail: %Schema{
252           type: :object,
253           properties: %{
254             url: %Schema{
255               type: :string,
256               description: "Banner image for the website",
257               nullable: true
258             }
259           }
260         },
261         languages: %Schema{
262           type: :array,
263           items: %Schema{type: :string},
264           description: "Primary languages of the website and its staff"
265         },
266         registrations: %Schema{
267           type: :object,
268           description: "Registrations-related configuration",
269           properties: %{
270             enabled: %Schema{
271               type: :boolean,
272               description: "Whether registrations are enabled"
273             },
274             approval_required: %Schema{
275               type: :boolean,
276               description: "Whether users need to be manually approved by admin"
277             }
278           }
279         },
280         configuration: %Schema{
281           type: :object,
282           description: "Instance configuration",
283           properties: %{
284             accounts: %Schema{
285               type: :object,
286               properties: %{
287                 max_featured_tags: %Schema{
288                   type: :integer,
289                   description: "The maximum number of featured tags allowed for each account."
290                 },
291                 max_pinned_statuses: %Schema{
292                   type: :integer,
293                   description: "The maximum number of pinned statuses for each account."
294                 }
295               }
296             },
297             urls: %Schema{
298               type: :object,
299               properties: %{
300                 streaming: %Schema{
301                   type: :string,
302                   description: "Websockets address for push streaming"
303                 }
304               }
305             },
306             statuses: %Schema{
307               type: :object,
308               description: "A map with poll limits for local statuses",
309               properties: %{
310                 characters_reserved_per_url: %Schema{
311                   type: :integer,
312                   description:
313                     "Each URL in a status will be assumed to be exactly this many characters."
314                 },
315                 max_characters: %Schema{
316                   type: :integer,
317                   description: "Posts character limit (CW/Subject included in the counter)"
318                 },
319                 max_media_attachments: %Schema{
320                   type: :integer,
321                   description: "Media attachment limit"
322                 }
323               }
324             },
325             media_attachments: %Schema{
326               type: :object,
327               description: "A map with poll limits for media attachments",
328               properties: %{
329                 image_size_limit: %Schema{
330                   type: :integer,
331                   description: "File size limit of uploaded images"
332                 },
333                 video_size_limit: %Schema{
334                   type: :integer,
335                   description: "File size limit of uploaded videos"
336                 }
337               }
338             },
339             polls: %Schema{
340               type: :object,
341               description: "A map with poll limits for local polls",
342               properties: %{
343                 max_options: %Schema{
344                   type: :integer,
345                   description: "Maximum number of options."
346                 },
347                 max_characters_per_option: %Schema{
348                   type: :integer,
349                   description: "Maximum number of characters per option."
350                 },
351                 min_expiration: %Schema{
352                   type: :integer,
353                   description: "Minimum expiration time (in seconds)."
354                 },
355                 max_expiration: %Schema{
356                   type: :integer,
357                   description: "Maximum expiration time (in seconds)."
358                 }
359               }
360             }
361           }
362         }
363       }
364     }
365   end
366
367   defp array_of_domains do
368     %Schema{
369       type: :array,
370       items: %Schema{type: :string},
371       example: ["pleroma.site", "lain.com", "bikeshed.party"]
372     }
373   end
374 end