View Javadoc
1   /*
2    * Copyright 2019-2020 the original author or authors.
3    *
4    * Licensed under the Apache License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at
7    *
8    *      http://www.apache.org/licenses/LICENSE-2.0
9    *
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS,
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   * See the License for the specific language governing permissions and
14   * limitations under the License.
15   */
16  
17  package org.bremersee.dccon.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 java.util.List;
28  import javax.validation.Valid;
29  import org.bremersee.common.model.TwoLetterLanguageCode;
30  import org.bremersee.dccon.model.AvatarDefault;
31  import org.bremersee.dccon.model.DomainUser;
32  import org.bremersee.dccon.model.Password;
33  import org.bremersee.exception.model.RestApiException;
34  import org.springframework.http.MediaType;
35  import org.springframework.http.ResponseEntity;
36  import org.springframework.validation.annotation.Validated;
37  import org.springframework.web.bind.annotation.PathVariable;
38  import org.springframework.web.bind.annotation.RequestBody;
39  import org.springframework.web.bind.annotation.RequestMapping;
40  import org.springframework.web.bind.annotation.RequestMethod;
41  import org.springframework.web.bind.annotation.RequestParam;
42  import org.springframework.web.multipart.MultipartFile;
43  
44  /**
45   * The domain user management api.
46   *
47   * @author Christian Bremer
48   */
49  @Tag(name = "domain-user-management-controller", description = "The domain user API.")
50  @Validated
51  public interface DomainUserManagementApi {
52  
53    /**
54     * Get domain users.
55     *
56     * @param sort the sort
57     * @param query the query
58     * @return the domain users
59     */
60    @Operation(
61        summary = "Get all domain users.",
62        operationId = "getUsers",
63        tags = {"domain-user-management-controller"})
64    @ApiResponses(value = {
65        @ApiResponse(
66            responseCode = "200",
67            description = "A list of domain users.",
68            content = @Content(
69                array = @ArraySchema(
70                    schema = @Schema(implementation = DomainUser.class)))),
71        @ApiResponse(
72            responseCode = "500",
73            description = "Fatal server error.",
74            content = @Content(
75                schema = @Schema(
76                    implementation = RestApiException.class)))
77    })
78    @RequestMapping(
79        value = "/api/users",
80        produces = {"application/json"},
81        method = RequestMethod.GET)
82    ResponseEntity<List<DomainUser>> getUsers(
83        @Parameter(description = "The sort order.")
84        @RequestParam(value = "sort",
85            defaultValue = DomainUser.DEFAULT_SORT_ORDER) String sort,
86  
87        @Parameter(description = "A query.")
88        @RequestParam(name = "q", required = false) String query);
89  
90    /**
91     * Add a domain user.
92     *
93     * @param email specifies whether to send an email or not (default is {@code false})
94     * @param language the language of the email
95     * @param domainUser the domain user to add
96     * @return the added domain user
97     */
98    @Operation(
99        summary = "Add domain user.",
100       operationId = "addUser",
101       tags = {"domain-user-management-controller"})
102   @ApiResponses(value = {
103       @ApiResponse(
104           responseCode = "200",
105           description = "The added domain user.",
106           content = @Content(
107               schema = @Schema(
108                   implementation = DomainUser.class))),
109       @ApiResponse(
110           responseCode = "400",
111           description = "Bad request.",
112           content = @Content(
113               schema = @Schema(
114                   implementation = RestApiException.class))),
115       @ApiResponse(
116           responseCode = "500",
117           description = "Fatal server error.",
118           content = @Content(
119               schema = @Schema(
120                   implementation = RestApiException.class)))
121   })
122   @RequestMapping(
123       value = "/api/users",
124       produces = {"application/json"},
125       consumes = {"application/json"},
126       method = RequestMethod.POST)
127   ResponseEntity<DomainUser> addUser(
128       @Parameter(description = "Specifies whether to send an email or not.")
129       @RequestParam(name = "email", defaultValue = "false") Boolean email,
130 
131       @Parameter(description = "The language of the email.")
132       @RequestParam(name = "lang", defaultValue = "en") TwoLetterLanguageCode language,
133 
134       @Parameter(description = "The domain user to add.", required = true)
135       @Valid @RequestBody DomainUser domainUser);
136 
137   /**
138    * Get domain user.
139    *
140    * @param userName the user name
141    * @return the domain user
142    */
143   @Operation(
144       summary = "Get a domain user by name.",
145       operationId = "getUser",
146       tags = {"domain-user-management-controller"})
147   @ApiResponses(value = {
148       @ApiResponse(
149           responseCode = "200",
150           description = "The domain user with the specified name.",
151           content = @Content(
152               schema = @Schema(
153                   implementation = DomainUser.class))),
154       @ApiResponse(
155           responseCode = "400",
156           description = "Bad request.",
157           content = @Content(
158               schema = @Schema(
159                   implementation = RestApiException.class))),
160       @ApiResponse(
161           responseCode = "404",
162           description = "Not found.",
163           content = @Content(
164               schema = @Schema(
165                   implementation = RestApiException.class))),
166       @ApiResponse(
167           responseCode = "500",
168           description = "Fatal server error.",
169           content = @Content(
170               schema = @Schema(
171                   implementation = RestApiException.class)))
172   })
173   @RequestMapping(
174       value = "/api/users/{userName}",
175       produces = {"application/json"},
176       method = RequestMethod.GET)
177   ResponseEntity<DomainUser> getUser(
178       @Parameter(description = "The user name of the domain user.", required = true)
179       @PathVariable("userName") String userName);
180 
181   /**
182    * Get avatar of domain user.
183    *
184    * @param userName the user name
185    * @param avatarDefault the default avatar
186    * @param size the size
187    * @return the avatar of the domain user
188    */
189   @Operation(
190       summary = "Get avatar of domain user.",
191       operationId = "getUserAvatar",
192       tags = {"domain-user-management-controller"})
193   @ApiResponses(value = {
194       @ApiResponse(
195           responseCode = "200",
196           description = "The avatar of the domain user.",
197           content = @Content(
198               schema = @Schema(
199                   implementation = byte[].class))),
200       @ApiResponse(
201           responseCode = "400",
202           description = "Bad request.",
203           content = @Content(
204               schema = @Schema(
205                   implementation = RestApiException.class))),
206       @ApiResponse(
207           responseCode = "404",
208           description = "Not found.",
209           content = @Content(
210               schema = @Schema(
211                   implementation = RestApiException.class))),
212       @ApiResponse(
213           responseCode = "500",
214           description = "Fatal server error.",
215           content = @Content(
216               schema = @Schema(
217                   implementation = RestApiException.class)))
218   })
219   @RequestMapping(
220       value = "/api/users/{userName}/avatar",
221       produces = {MediaType.IMAGE_JPEG_VALUE},
222       method = RequestMethod.GET)
223   ResponseEntity<byte[]> getUserAvatar(
224       @Parameter(description = "The user name of the domain user.", required = true)
225       @PathVariable("userName") String userName,
226 
227       @Parameter(description = "Return a default avatar if no one exits.")
228       @RequestParam(name = "d", defaultValue = "NOT_FOUND") AvatarDefault avatarDefault,
229 
230       @Parameter(description = "The size of the avatar.")
231       @RequestParam(name = "s", defaultValue = "80") Integer size);
232 
233   /**
234    * Update domain user.
235    *
236    * @param userName the user name
237    * @param updateGroups the update groups flag (default is false)
238    * @param domainUser the domain user
239    * @return the updated domain user
240    */
241   @Operation(
242       summary = "Updates a domain user.",
243       operationId = "updateUser",
244       tags = {"domain-user-management-controller"})
245   @ApiResponses(value = {
246       @ApiResponse(
247           responseCode = "200",
248           description = "The updated domain user.",
249           content = @Content(
250               schema = @Schema(
251                   implementation = DomainUser.class))),
252       @ApiResponse(
253           responseCode = "400",
254           description = "Bad request.",
255           content = @Content(
256               schema = @Schema(
257                   implementation = RestApiException.class))),
258       @ApiResponse(
259           responseCode = "404",
260           description = "Not found.",
261           content = @Content(
262               schema = @Schema(
263                   implementation = RestApiException.class))),
264       @ApiResponse(
265           responseCode = "500",
266           description = "Fatal server error.",
267           content = @Content(
268               schema = @Schema(
269                   implementation = RestApiException.class)))
270   })
271   @RequestMapping(
272       value = "/api/users/{userName}",
273       produces = {"application/json"},
274       consumes = {"application/json"},
275       method = RequestMethod.PUT)
276   ResponseEntity<DomainUser> updateUser(
277       @Parameter(description = "The user name of the domain user.", required = true)
278       @PathVariable("userName") String userName,
279 
280       @Parameter(description = "Specifies whether the groups should also be updated or not.")
281       @RequestParam(name = "updateGroups", defaultValue = "false") Boolean updateGroups,
282 
283       @Parameter(description = "The domain user.", required = true)
284       @Valid @RequestBody DomainUser domainUser);
285 
286   /**
287    * Update user password.
288    *
289    * @param userName the user name
290    * @param email specifies whether to send an email or not (default is {@code false})
291    * @param language the language of the email
292    * @param newPassword the new password
293    * @return void response entity
294    */
295   @Operation(
296       summary = "Updates the password of the domain user.",
297       operationId = "updateUserPassword",
298       tags = {"domain-user-management-controller"})
299   @ApiResponses(value = {
300       @ApiResponse(
301           responseCode = "200",
302           description = "The password was successfully changed."),
303       @ApiResponse(
304           responseCode = "400",
305           description = "Bad request.",
306           content = @Content(
307               schema = @Schema(
308                   implementation = RestApiException.class))),
309       @ApiResponse(
310           responseCode = "404",
311           description = "Not found.",
312           content = @Content(
313               schema = @Schema(
314                   implementation = RestApiException.class))),
315       @ApiResponse(
316           responseCode = "500",
317           description = "Fatal server error.",
318           content = @Content(
319               schema = @Schema(
320                   implementation = RestApiException.class)))
321   })
322   @RequestMapping(
323       value = "/api/users/{userName}/password",
324       produces = {"application/json"},
325       consumes = {"application/json"},
326       method = RequestMethod.PUT)
327   ResponseEntity<Void> updateUserPassword(
328       @Parameter(description = "The user name of the domain user.", required = true)
329       @PathVariable("userName") String userName,
330 
331       @Parameter(description = "Specifies whether to send an email or not.")
332       @RequestParam(name = "email", defaultValue = "false") Boolean email,
333 
334       @Parameter(description = "The language of the email.")
335       @RequestParam(name = "lang", defaultValue = "en") TwoLetterLanguageCode language,
336 
337       @Parameter(description = "The password of the domain user.", required = true)
338       @Valid @RequestBody Password newPassword);
339 
340   /**
341    * Update user avatar response entity.
342    *
343    * @param userName the user name
344    * @param avatar the avatar
345    * @return the response entity
346    */
347   @Operation(
348       summary = "Updates avatar of the domain user.",
349       operationId = "updateUserAvatar",
350       tags = {"domain-user-management-controller"})
351   @ApiResponses(value = {
352       @ApiResponse(
353           responseCode = "200",
354           description = "The avatar was successfully updated."),
355       @ApiResponse(
356           responseCode = "400",
357           description = "Bad request.",
358           content = @Content(
359               schema = @Schema(
360                   implementation = RestApiException.class))),
361       @ApiResponse(
362           responseCode = "404",
363           description = "Not found.",
364           content = @Content(
365               schema = @Schema(
366                   implementation = RestApiException.class))),
367       @ApiResponse(
368           responseCode = "500",
369           description = "Fatal server error.",
370           content = @Content(
371               schema = @Schema(
372                   implementation = RestApiException.class)))
373   })
374   @RequestMapping(
375       value = "/api/users/{userName}/avatar",
376       consumes = {"multipart/form-data"},
377       method = RequestMethod.POST)
378   ResponseEntity<Void> updateUserAvatar(
379       @Parameter(description = "The user name of the domain user.", required = true)
380       @PathVariable("userName") String userName,
381 
382       @Parameter(description = "The avatar.", required = true)
383       @RequestParam("avatar") MultipartFile avatar);
384 
385   /**
386    * Remove user avatar response entity.
387    *
388    * @param userName the user name
389    * @return the response entity
390    */
391   @Operation(
392       summary = "Removes avatar of the domain user.",
393       operationId = "removeUserAvatar",
394       tags = {"domain-user-management-controller"})
395   @ApiResponses(value = {
396       @ApiResponse(
397           responseCode = "200",
398           description = "The avatar was successfully removed."),
399       @ApiResponse(
400           responseCode = "400",
401           description = "Bad request.",
402           content = @Content(
403               schema = @Schema(
404                   implementation = RestApiException.class))),
405       @ApiResponse(
406           responseCode = "404",
407           description = "Not found.",
408           content = @Content(
409               schema = @Schema(
410                   implementation = RestApiException.class))),
411       @ApiResponse(
412           responseCode = "500",
413           description = "Fatal server error.",
414           content = @Content(
415               schema = @Schema(
416                   implementation = RestApiException.class)))
417   })
418   @RequestMapping(
419       value = "/api/users/{userName}/avatar",
420       method = RequestMethod.DELETE)
421   ResponseEntity<Void> removeUserAvatar(
422       @Parameter(description = "The user name of the domain user.", required = true)
423       @PathVariable("userName") String userName);
424 
425   /**
426    * Checks whether a domain user exists.
427    *
428    * @param userName the user name
429    * @return true if the user exists otherwise false
430    */
431   @Operation(
432       summary = "Checks whether a domain user exists.",
433       operationId = "userExists",
434       tags = {"domain-user-management-controller"})
435   @ApiResponses(value = {
436       @ApiResponse(
437           responseCode = "200",
438           description = "True if the user exists otherwise false.",
439           content = @Content(
440               schema = @Schema(
441                   implementation = Boolean.class))),
442       @ApiResponse(
443           responseCode = "500",
444           description = "Fatal server error.",
445           content = @Content(
446               schema = @Schema(
447                   implementation = RestApiException.class)))
448   })
449   @RequestMapping(value = "/api/users/{userName}/exists",
450       produces = {"application/json"},
451       method = RequestMethod.GET)
452   ResponseEntity<Boolean> userExists(
453       @Parameter(description = "The user name of the domain user.",
454           required = true) @PathVariable("userName") String userName);
455 
456   /**
457    * Checks whether a user name is in use or not.
458    *
459    * @param userName the user name
460    * @return true if the user name is in use otherwise false
461    */
462   @Operation(
463       summary = "Checks whether a user name is in use or not.",
464       operationId = "isUserNameInUse",
465       tags = {"domain-user-management-controller"})
466   @ApiResponses(value = {
467       @ApiResponse(
468           responseCode = "200",
469           description = "True if the user name is in use otherwise false.",
470           content = @Content(
471               schema = @Schema(
472                   implementation = Boolean.class))),
473       @ApiResponse(
474           responseCode = "500",
475           description = "Fatal server error.",
476           content = @Content(
477               schema = @Schema(
478                   implementation = RestApiException.class)))
479   })
480   @RequestMapping(value = "/api/users/{userName}/in-use",
481       produces = {"application/json"},
482       method = RequestMethod.GET)
483   ResponseEntity<Boolean> isUserNameInUse(
484       @Parameter(description = "The user name of the domain user.",
485           required = true) @PathVariable("userName") String userName);
486 
487   /**
488    * Delete domain user.
489    *
490    * @param userName the user name
491    * @return {@code true} if the domain user was deleted, otherwise {@code false}
492    */
493   @Operation(
494       summary = "Delete domain user.",
495       operationId = "deleteUser",
496       tags = {"domain-user-management-controller"})
497   @ApiResponses(value = {
498       @ApiResponse(
499           responseCode = "200",
500           description = "True if the domain user was successfully deleted, otherwise false.",
501           content = @Content(
502               schema = @Schema(
503                   implementation = Boolean.class))),
504       @ApiResponse(
505           responseCode = "400",
506           description = "Bad request.",
507           content = @Content(
508               schema = @Schema(
509                   implementation = RestApiException.class))),
510       @ApiResponse(
511           responseCode = "500",
512           description = "Fatal server error.",
513           content = @Content(
514               schema = @Schema(
515                   implementation = RestApiException.class)))
516   })
517   @RequestMapping(value = "/api/users/{userName}",
518       produces = {"application/json"},
519       method = RequestMethod.DELETE)
520   ResponseEntity<Boolean> deleteUser(
521       @Parameter(description = "The user name of the domain user.", required = true)
522       @PathVariable("userName") String userName);
523 
524 }