1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17 package org.bremersee.groupman.api;
18
19 import io.swagger.v3.oas.annotations.Operation;
20 import io.swagger.v3.oas.annotations.Parameter;
21 import io.swagger.v3.oas.annotations.media.ArraySchema;
22 import io.swagger.v3.oas.annotations.media.Content;
23 import io.swagger.v3.oas.annotations.media.Schema;
24 import io.swagger.v3.oas.annotations.responses.ApiResponse;
25 import io.swagger.v3.oas.annotations.responses.ApiResponses;
26 import io.swagger.v3.oas.annotations.tags.Tag;
27 import jakarta.validation.Valid;
28 import java.util.List;
29 import org.bremersee.groupman.model.Group;
30 import org.bremersee.groupman.model.GroupIdList;
31 import org.bremersee.groupman.model.Status;
32 import org.springframework.http.ResponseEntity;
33 import org.springframework.web.bind.annotation.PathVariable;
34 import org.springframework.web.bind.annotation.RequestBody;
35 import org.springframework.web.bind.annotation.RequestMapping;
36 import org.springframework.web.bind.annotation.RequestMethod;
37 import org.springframework.web.bind.annotation.RequestParam;
38
39
40
41
42
43
44 @Tag(name = "group-controller", description = "The group API.")
45 @Valid
46 public interface GroupControllerApi {
47
48
49
50
51
52
53
54 @Operation(
55 summary = "Create a new group.",
56 operationId = "createGroup",
57 tags = {"group-controller"})
58 @ApiResponses(value = {
59 @ApiResponse(
60 responseCode = "200",
61 description = "The created group.",
62 content = @Content(
63 schema = @Schema(
64 implementation = Group.class))),
65 @ApiResponse(
66 responseCode = "400",
67 description = "Bad Request",
68 content = @Content(
69 schema = @Schema(
70 implementation = org.bremersee.exception.model.RestApiException.class))),
71 @ApiResponse(
72 responseCode = "409",
73 description = "Group already exists",
74 content = @Content(
75 schema = @Schema(
76 implementation = org.bremersee.exception.model.RestApiException.class)))
77 })
78 @RequestMapping(
79 value = "/api/groups",
80 produces = {"application/json"},
81 consumes = {"application/json"},
82 method = RequestMethod.POST)
83 ResponseEntity<Group> createGroup(
84 @Parameter(description = "The new group.", required = true) @Valid @RequestBody Group group);
85
86
87
88
89
90
91
92
93 @Operation(
94 summary = "Get a group.",
95 operationId = "getGroupById",
96 tags = {"group-controller"})
97 @ApiResponses(value = {
98 @ApiResponse(
99 responseCode = "200",
100 description = "The group.",
101 content = @Content(
102 schema = @Schema(
103 implementation = Group.class))),
104 @ApiResponse(
105 responseCode = "404",
106 description = "Not Found",
107 content = @Content(
108 schema = @Schema(
109 implementation = org.bremersee.exception.model.RestApiException.class)))
110 })
111 @RequestMapping(
112 value = "/api/groups/{id}",
113 produces = {"application/json"},
114 method = RequestMethod.GET)
115 ResponseEntity<Group> getGroupById(
116 @Parameter(description = "The group ID.", required = true) @PathVariable("id") String id);
117
118
119
120
121
122
123
124
125
126 @Operation(
127 summary = "Update group.",
128 operationId = "updateGroup",
129 tags = {"group-controller"})
130 @ApiResponses(value = {
131 @ApiResponse(
132 responseCode = "200",
133 description = "The updated group.",
134 content = @Content(
135 schema = @Schema(
136 implementation = Group.class))),
137 @ApiResponse(
138 responseCode = "400",
139 description = "Bad Request",
140 content = @Content(
141 schema = @Schema(
142 implementation = org.bremersee.exception.model.RestApiException.class))),
143 @ApiResponse(
144 responseCode = "403",
145 description = "Forbidden"),
146 @ApiResponse(
147 responseCode = "404",
148 description = "Not Found",
149 content = @Content(
150 schema = @Schema(
151 implementation = org.bremersee.exception.model.RestApiException.class))),
152 @ApiResponse(
153 responseCode = "409",
154 description = "Version is not up to date",
155 content = @Content(
156 schema = @Schema(
157 implementation = org.bremersee.exception.model.RestApiException.class)))
158 })
159 @RequestMapping(
160 value = "/api/groups/{id}",
161 produces = {"application/json"},
162 consumes = {"application/json"},
163 method = RequestMethod.PUT)
164 ResponseEntity<Group> updateGroup(
165 @Parameter(description = "The group ID.", required = true) @PathVariable("id") String id,
166 @Parameter(description = "The group.", required = true) @Valid @RequestBody Group group);
167
168
169
170
171
172
173
174
175 @Operation(
176 summary = "Delete a group.",
177 operationId = "deleteGroup",
178 tags = {"group-controller"})
179 @ApiResponses(value = {
180 @ApiResponse(
181 responseCode = "200",
182 description = "OK"),
183 @ApiResponse(
184 responseCode = "403",
185 description = "Forbidden"),
186 @ApiResponse(
187 responseCode = "404",
188 description = "Not Found",
189 content = @Content(
190 schema = @Schema(
191 implementation = org.bremersee.exception.model.RestApiException.class)))
192 })
193 @RequestMapping(
194 value = "/api/groups/{id}",
195 method = RequestMethod.DELETE)
196 ResponseEntity<Group> deleteGroup(
197 @Parameter(description = "The group ID.", required = true) @PathVariable("id") String id);
198
199
200
201
202
203
204
205
206 @Operation(
207 summary = "Get groups by id.",
208 operationId = "getGroupsByIds",
209 tags = {"group-controller"})
210 @ApiResponses(value = {
211 @ApiResponse(
212 responseCode = "200",
213 description = "The groups.",
214 content = @Content(
215 array = @ArraySchema(
216 schema = @Schema(implementation = Group.class))))
217 })
218 @RequestMapping(
219 value = "/api/groups/f",
220 produces = {"application/json"},
221 method = RequestMethod.GET)
222 ResponseEntity<List<Group>> getGroupsByIds(
223 @Parameter(description = "Group IDs")
224 @RequestParam(value = "id", required = false) List<String> id);
225
226
227
228
229
230
231
232 @Operation(
233 summary = "Get editable groups.",
234 operationId = "getEditableGroups",
235 tags = {"group-controller"})
236 @ApiResponses(value = {
237 @ApiResponse(
238 responseCode = "200",
239 description = "The groups.",
240 content = @Content(
241 array = @ArraySchema(
242 schema = @Schema(implementation = Group.class))))
243 })
244 @RequestMapping(
245 value = "/api/groups/f/editable",
246 produces = {"application/json"},
247 method = RequestMethod.GET)
248 ResponseEntity<List<Group>> getEditableGroups();
249
250
251
252
253
254
255
256 @Operation(
257 summary = "Get usable groups.",
258 operationId = "getUsableGroups",
259 tags = {"group-controller"})
260 @ApiResponses(value = {
261 @ApiResponse(
262 responseCode = "200",
263 description = "The groups.",
264 content = @Content(
265 array = @ArraySchema(
266 schema = @Schema(implementation = Group.class))))
267 })
268 @RequestMapping(
269 value = "/api/groups/f/usable",
270 produces = {"application/json"},
271 method = RequestMethod.GET)
272 ResponseEntity<List<Group>> getUsableGroups();
273
274
275
276
277
278
279
280 @Operation(
281 summary = "Get membership.",
282 operationId = "getMembership",
283 tags = {"group-controller"})
284 @ApiResponses(value = {
285 @ApiResponse(
286 responseCode = "200",
287 description = "The groups.",
288 content = @Content(
289 array = @ArraySchema(
290 schema = @Schema(implementation = Group.class))))
291 })
292 @RequestMapping(
293 value = "/api/groups/f/membership",
294 produces = {"application/json"},
295 method = RequestMethod.GET)
296 ResponseEntity<List<Group>> getMembership();
297
298
299
300
301
302
303
304 @Operation(
305 summary = "Get membership IDs.",
306 operationId = "getMembershipIds",
307 tags = {"group-controller"})
308 @ApiResponses(value = {
309 @ApiResponse(
310 responseCode = "200",
311 description = "The group IDs.",
312 content = @Content(
313 array = @ArraySchema(
314 schema = @Schema(implementation = String.class))))
315 })
316 @RequestMapping(
317 value = "/api/groups/f/membership-ids",
318 produces = {"application/json"},
319 method = RequestMethod.GET)
320 ResponseEntity<GroupIdList> getMembershipIds();
321
322
323
324
325
326
327 @Operation(
328 summary = "Get status of the current user.",
329 operationId = "getStatus",
330 tags = {"group-controller"})
331 @ApiResponses(value = {
332 @ApiResponse(
333 responseCode = "200",
334 description = "The user status.",
335 content = @Content(
336 schema = @Schema(
337 implementation = Status.class)))
338 })
339 @RequestMapping(
340 value = "/api/groups/f/status",
341 produces = {"application/json"},
342 method = RequestMethod.GET)
343 ResponseEntity<Status> getStatus();
344
345 }