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