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.dccon.model.DomainGroup;
30  import org.bremersee.exception.model.RestApiException;
31  import org.springframework.http.ResponseEntity;
32  import org.springframework.validation.annotation.Validated;
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   * The domain group management api.
41   *
42   * @author Christian Bremer
43   */
44  @Tag(name = "domain-group-management-controller", description = "The domain group API.")
45  @Validated
46  public interface DomainGroupManagementApi {
47  
48    /**
49     * Get domain groups.
50     *
51     * @param sort the sort order
52     * @param query the query
53     * @return the groups
54     */
55    @Operation(
56        summary = "Get all domain groups.",
57        operationId = "getGroups",
58        tags = {"domain-group-management-controller"})
59    @ApiResponses(value = {
60        @ApiResponse(
61            responseCode = "200",
62            description = "A list of domain groups.",
63            content = @Content(
64                array = @ArraySchema(
65                    schema = @Schema(implementation = DomainGroup.class)))),
66        @ApiResponse(
67            responseCode = "500",
68            description = "Fatal server error.",
69            content = @Content(
70                schema = @Schema(
71                    implementation = RestApiException.class)))
72    })
73    @RequestMapping(
74        value = "/api/groups",
75        produces = {"application/json"},
76        method = RequestMethod.GET)
77    ResponseEntity<List<DomainGroup>> getGroups(
78        @Parameter(description = "The sort order.")
79        @RequestParam(value = "sort",
80            defaultValue = DomainGroup.DEFAULT_SORT_ORDER) String sort,
81  
82        @Parameter(description = "A query.")
83        @RequestParam(name = "q", required = false) String query);
84  
85    /**
86     * Add domain group.
87     *
88     * @param group the domain group to add
89     * @return the added domain group
90     */
91    @Operation(
92        summary = "Add domain group.",
93        operationId = "addGroup",
94        tags = {"domain-group-management-controller"})
95    @ApiResponses(value = {
96        @ApiResponse(
97            responseCode = "200",
98            description = "The added domain group.",
99            content = @Content(
100               schema = @Schema(
101                   implementation = DomainGroup.class))),
102       @ApiResponse(
103           responseCode = "400",
104           description = "Bad request.",
105           content = @Content(
106               schema = @Schema(
107                   implementation = RestApiException.class))),
108       @ApiResponse(
109           responseCode = "406",
110           description = "Already exists.",
111           content = @Content(
112               schema = @Schema(
113                   implementation = RestApiException.class))),
114       @ApiResponse(
115           responseCode = "500",
116           description = "Fatal server error.",
117           content = @Content(
118               schema = @Schema(
119                   implementation = RestApiException.class)))
120   })
121   @RequestMapping(
122       value = "/api/groups",
123       produces = {"application/json"},
124       consumes = {"application/json"},
125       method = RequestMethod.POST)
126   ResponseEntity<DomainGroup> addGroup(
127       @Parameter(description = "The domain group to add.", required = true)
128       @Valid @RequestBody DomainGroup group);
129 
130   /**
131    * Get domain group by name.
132    *
133    * @param groupName the group name
134    * @return the domain group
135    */
136   @Operation(
137       summary = "Get a domain group by name.",
138       operationId = "getGroupByName",
139       tags = {"domain-group-management-controller"})
140   @ApiResponses(value = {
141       @ApiResponse(
142           responseCode = "200",
143           description = "The domain group with the specified name.",
144           content = @Content(
145               schema = @Schema(
146                   implementation = DomainGroup.class))),
147       @ApiResponse(
148           responseCode = "400",
149           description = "Bad request.",
150           content = @Content(
151               schema = @Schema(
152                   implementation = RestApiException.class))),
153       @ApiResponse(
154           responseCode = "404",
155           description = "Not found.",
156           content = @Content(
157               schema = @Schema(
158                   implementation = RestApiException.class))),
159       @ApiResponse(
160           responseCode = "500",
161           description = "Fatal server error.",
162           content = @Content(
163               schema = @Schema(
164                   implementation = RestApiException.class)))
165   })
166   @RequestMapping(
167       value = "/api/groups/{groupName}",
168       produces = {"application/json"},
169       method = RequestMethod.GET)
170   ResponseEntity<DomainGroup> getGroup(
171       @Parameter(description = "The domain group name.", required = true)
172       @PathVariable("groupName") String groupName);
173 
174   /**
175    * Update domain group.
176    *
177    * @param groupName the group name
178    * @param domainGroup the domain group
179    * @return the updated domain group
180    */
181   @Operation(
182       summary = "Updates a domain group.",
183       operationId = "updateGroup",
184       tags = {"domain-group-management-controller"})
185   @ApiResponses(value = {
186       @ApiResponse(
187           responseCode = "200",
188           description = "The updated domain group.",
189           content = @Content(
190               schema = @Schema(
191                   implementation = DomainGroup.class))),
192       @ApiResponse(
193           responseCode = "400",
194           description = "Bad request.",
195           content = @Content(
196               schema = @Schema(
197                   implementation = RestApiException.class))),
198       @ApiResponse(
199           responseCode = "404",
200           description = "Not found.",
201           content = @Content(
202               schema = @Schema(
203                   implementation = RestApiException.class))),
204       @ApiResponse(
205           responseCode = "500",
206           description = "Fatal server error.",
207           content = @Content(
208               schema = @Schema(
209                   implementation = RestApiException.class)))
210   })
211   @RequestMapping(
212       value = "/api/groups/{groupName}",
213       produces = {"application/json"},
214       consumes = {"application/json"},
215       method = RequestMethod.PUT)
216   ResponseEntity<DomainGroup> updateGroup(
217       @Parameter(description = "The name of the domain group.", required = true)
218       @PathVariable("groupName") String groupName,
219 
220       @Parameter(description = "The domain group.", required = true)
221       @Valid @RequestBody DomainGroup domainGroup);
222 
223   /**
224    * Checks whether a domain group exists.
225    *
226    * @param groupName the group name
227    * @return true if the group exists otherwise false
228    */
229   @Operation(
230       summary = "Checks whether a domain group exists.",
231       operationId = "groupExists",
232       tags = {"domain-group-management-controller"})
233   @ApiResponses(value = {
234       @ApiResponse(
235           responseCode = "200",
236           description = "True if the group exists otherwise false.",
237           content = @Content(
238               schema = @Schema(
239                   implementation = Boolean.class))),
240       @ApiResponse(
241           responseCode = "500",
242           description = "Fatal server error.",
243           content = @Content(
244               schema = @Schema(
245                   implementation = RestApiException.class)))
246   })
247   @RequestMapping(value = "/api/groups/{groupName}/exists",
248       produces = {"application/json"},
249       method = RequestMethod.GET)
250   ResponseEntity<Boolean> groupExists(
251       @Parameter(description = "The name of the domain group.", required = true)
252       @PathVariable("groupName") String groupName);
253 
254   /**
255    * Checks whether a group is in use or not.
256    *
257    * @param groupName the group name
258    * @return true if the group name is in use otherwise false
259    */
260   @Operation(
261       summary = "Checks whether a group is in use or not.",
262       operationId = "isGroupNameInUse",
263       tags = {"domain-group-management-controller"})
264   @ApiResponses(value = {
265       @ApiResponse(
266           responseCode = "200",
267           description = "True if the group name is in use otherwise false.",
268           content = @Content(
269               schema = @Schema(
270                   implementation = Boolean.class))),
271       @ApiResponse(
272           responseCode = "500",
273           description = "Fatal server error.",
274           content = @Content(
275               schema = @Schema(
276                   implementation = RestApiException.class)))
277   })
278   @RequestMapping(value = "/api/groups/{groupName}/in-use",
279       produces = {"application/json"},
280       method = RequestMethod.GET)
281   ResponseEntity<Boolean> isGroupNameInUse(
282       @Parameter(description = "The name of the domain group.", required = true)
283       @PathVariable("groupName") String groupName);
284 
285   /**
286    * Delete domain group.
287    *
288    * @param groupName the group name
289    * @return {@code true} if the domain group was deleted, otherwise {@code false}
290    */
291   @Operation(
292       summary = "Delete domain group.",
293       operationId = "deleteGroup",
294       tags = {"domain-group-management-controller"})
295   @ApiResponses(value = {
296       @ApiResponse(
297           responseCode = "200",
298           description = "True if the domain group was successfully deleted, otherwise false.",
299           content = @Content(
300               schema = @Schema(
301                   implementation = Boolean.class))),
302       @ApiResponse(
303           responseCode = "400",
304           description = "Bad request.",
305           content = @Content(
306               schema = @Schema(
307                   implementation = RestApiException.class))),
308       @ApiResponse(
309           responseCode = "500",
310           description = "Fatal server error.",
311           content = @Content(
312               schema = @Schema(
313                   implementation = RestApiException.class)))
314   })
315   @RequestMapping(
316       value = "/api/groups/{groupName}",
317       produces = {"application/json"},
318       method = RequestMethod.DELETE)
319   ResponseEntity<Boolean> deleteGroup(
320       @Parameter(description = "The domain group name.", required = true)
321       @PathVariable("groupName") String groupName);
322 
323 }