Merge branch 'develop' into feature/bulk-confirmation
[akkoma] / lib / pleroma / web / api_spec / operations / list_operation.ex
1 # Pleroma: A lightweight social networking server
2 # Copyright © 2017-2020 Pleroma Authors <https://pleroma.social/>
3 # SPDX-License-Identifier: AGPL-3.0-only
4
5 defmodule Pleroma.Web.ApiSpec.ListOperation do
6 alias OpenApiSpex.Operation
7 alias OpenApiSpex.Schema
8 alias Pleroma.Web.ApiSpec.Schemas.Account
9 alias Pleroma.Web.ApiSpec.Schemas.ApiError
10 alias Pleroma.Web.ApiSpec.Schemas.FlakeID
11 alias Pleroma.Web.ApiSpec.Schemas.List
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 index_operation do
21 %Operation{
22 tags: ["Lists"],
23 summary: "Show user's lists",
24 description: "Fetch all lists that the user owns",
25 security: [%{"oAuth" => ["read:lists"]}],
26 operationId: "ListController.index",
27 responses: %{
28 200 => Operation.response("Array of List", "application/json", array_of_lists())
29 }
30 }
31 end
32
33 def create_operation do
34 %Operation{
35 tags: ["Lists"],
36 summary: "Create a list",
37 description: "Fetch the list with the given ID. Used for verifying the title of a list.",
38 operationId: "ListController.create",
39 requestBody: create_update_request(),
40 security: [%{"oAuth" => ["write:lists"]}],
41 responses: %{
42 200 => Operation.response("List", "application/json", List),
43 400 => Operation.response("Error", "application/json", ApiError),
44 404 => Operation.response("Error", "application/json", ApiError)
45 }
46 }
47 end
48
49 def show_operation do
50 %Operation{
51 tags: ["Lists"],
52 summary: "Show a single list",
53 description: "Fetch the list with the given ID. Used for verifying the title of a list.",
54 operationId: "ListController.show",
55 parameters: [id_param()],
56 security: [%{"oAuth" => ["read:lists"]}],
57 responses: %{
58 200 => Operation.response("List", "application/json", List),
59 404 => Operation.response("Error", "application/json", ApiError)
60 }
61 }
62 end
63
64 def update_operation do
65 %Operation{
66 tags: ["Lists"],
67 summary: "Update a list",
68 description: "Change the title of a list",
69 operationId: "ListController.update",
70 parameters: [id_param()],
71 requestBody: create_update_request(),
72 security: [%{"oAuth" => ["write:lists"]}],
73 responses: %{
74 200 => Operation.response("List", "application/json", List),
75 422 => Operation.response("Error", "application/json", ApiError)
76 }
77 }
78 end
79
80 def delete_operation do
81 %Operation{
82 tags: ["Lists"],
83 summary: "Delete a list",
84 operationId: "ListController.delete",
85 parameters: [id_param()],
86 security: [%{"oAuth" => ["write:lists"]}],
87 responses: %{
88 200 => Operation.response("Empty object", "application/json", %Schema{type: :object})
89 }
90 }
91 end
92
93 def list_accounts_operation do
94 %Operation{
95 tags: ["Lists"],
96 summary: "View accounts in list",
97 operationId: "ListController.list_accounts",
98 parameters: [id_param()],
99 security: [%{"oAuth" => ["read:lists"]}],
100 responses: %{
101 200 =>
102 Operation.response("Array of Account", "application/json", %Schema{
103 type: :array,
104 items: Account
105 })
106 }
107 }
108 end
109
110 def add_to_list_operation do
111 %Operation{
112 tags: ["Lists"],
113 summary: "Add accounts to list",
114 description: "Add accounts to the given list.",
115 operationId: "ListController.add_to_list",
116 parameters: [id_param()],
117 requestBody: add_remove_accounts_request(true),
118 security: [%{"oAuth" => ["write:lists"]}],
119 responses: %{
120 200 => Operation.response("Empty object", "application/json", %Schema{type: :object})
121 }
122 }
123 end
124
125 def remove_from_list_operation do
126 %Operation{
127 tags: ["Lists"],
128 summary: "Remove accounts from list",
129 operationId: "ListController.remove_from_list",
130 parameters: [
131 id_param(),
132 Operation.parameter(
133 :account_ids,
134 :query,
135 %Schema{type: :array, items: %Schema{type: :string}},
136 "Array of account IDs"
137 )
138 ],
139 requestBody: add_remove_accounts_request(false),
140 security: [%{"oAuth" => ["write:lists"]}],
141 responses: %{
142 200 => Operation.response("Empty object", "application/json", %Schema{type: :object})
143 }
144 }
145 end
146
147 defp array_of_lists do
148 %Schema{
149 title: "ArrayOfLists",
150 description: "Response schema for lists",
151 type: :array,
152 items: List,
153 example: [
154 %{"id" => "123", "title" => "my list"},
155 %{"id" => "1337", "title" => "another list"}
156 ]
157 }
158 end
159
160 defp id_param do
161 Operation.parameter(:id, :path, :string, "List ID",
162 example: "123",
163 required: true
164 )
165 end
166
167 defp create_update_request do
168 request_body(
169 "Parameters",
170 %Schema{
171 description: "POST body for creating or updating a List",
172 type: :object,
173 properties: %{
174 title: %Schema{type: :string, description: "List title"}
175 },
176 required: [:title]
177 },
178 required: true
179 )
180 end
181
182 defp add_remove_accounts_request(required) when is_boolean(required) do
183 request_body(
184 "Parameters",
185 %Schema{
186 description: "POST body for adding/removing accounts to/from a List",
187 type: :object,
188 properties: %{
189 account_ids: %Schema{type: :array, description: "Array of account IDs", items: FlakeID}
190 }
191 },
192 required: required
193 )
194 end
195 end