From 5869719c150828615c4cbc4a3ef429280c43327d Mon Sep 17 00:00:00 2001 From: Ali Oezyetimoglu Date: Thu, 7 Sep 2023 10:54:49 +0200 Subject: [PATCH] TAAS-88: updated documentation of endpoints and models --- .../api/external/GeneralSettingsResource.java | 6 ++--- .../external/SMTPConfigurationResource.java | 10 +++---- .../api/external/TenantsResource.java | 8 +++--- .../api/external/UserPreferenceResource.java | 6 ++--- .../api/external/UserResource.java | 26 +++++++++---------- .../model/GeneralConfigurationModel.java | 2 +- .../model/ResetPasswordRequest.java | 2 +- .../model/TenantUser.java | 2 +- 8 files changed, 31 insertions(+), 31 deletions(-) diff --git a/src/main/java/com/knecon/fforesight/tenantusermanagement/api/external/GeneralSettingsResource.java b/src/main/java/com/knecon/fforesight/tenantusermanagement/api/external/GeneralSettingsResource.java index e6f29a2..95ef3b0 100644 --- a/src/main/java/com/knecon/fforesight/tenantusermanagement/api/external/GeneralSettingsResource.java +++ b/src/main/java/com/knecon/fforesight/tenantusermanagement/api/external/GeneralSettingsResource.java @@ -22,15 +22,15 @@ public interface GeneralSettingsResource { @ResponseBody @ResponseStatus(value = HttpStatus.OK) @GetMapping(value = API_PATH, produces = MediaType.APPLICATION_JSON_VALUE) - @Operation(summary = "Returns the current general Configuration.") + @Operation(summary = "Returns the current general configuration") @ApiResponses(value = {@ApiResponse(responseCode = "200", description = "OK.")}) GeneralConfigurationModel getGeneralConfigurations(); @ResponseStatus(value = HttpStatus.NO_CONTENT) @PostMapping(value = API_PATH, consumes = MediaType.APPLICATION_JSON_VALUE) - @Operation(summary = "Write General Configurations to KeyCloak") - @ApiResponses(value = {@ApiResponse(responseCode = "204", description = "General Configuration updated successful."), @ApiResponse(responseCode = "400", description = "General Configuration update failed.")}) + @Operation(summary = "Write general configuration to KeyCloak") + @ApiResponses(value = {@ApiResponse(responseCode = "204", description = "General configuration updated successful."), @ApiResponse(responseCode = "400", description = "General configuration update failed.")}) void updateGeneralConfigurations(@RequestBody GeneralConfigurationModel generalConfigurationModel); } diff --git a/src/main/java/com/knecon/fforesight/tenantusermanagement/api/external/SMTPConfigurationResource.java b/src/main/java/com/knecon/fforesight/tenantusermanagement/api/external/SMTPConfigurationResource.java index af6c2be..1cdb49c 100644 --- a/src/main/java/com/knecon/fforesight/tenantusermanagement/api/external/SMTPConfigurationResource.java +++ b/src/main/java/com/knecon/fforesight/tenantusermanagement/api/external/SMTPConfigurationResource.java @@ -26,7 +26,7 @@ public interface SMTPConfigurationResource { @ResponseBody @ResponseStatus(value = HttpStatus.OK) @GetMapping(value = SMTP_PATH, produces = MediaType.APPLICATION_JSON_VALUE) - @Operation(summary = "Returns the current SMTP Configuration.") + @Operation(summary = "Returns the current SMTP configuration.") @ApiResponses(value = {@ApiResponse(responseCode = "200", description = "OK."), @ApiResponse(responseCode = "404", description = "SMTP not configured.")}) SMTPConfiguration getCurrentSMTPConfiguration(); @@ -34,7 +34,7 @@ public interface SMTPConfigurationResource { @ResponseStatus(value = HttpStatus.NO_CONTENT) @PostMapping(value = SMTP_PATH, consumes = MediaType.APPLICATION_JSON_VALUE) @Operation(summary = "Write SMTP Settings to KeyCloak") - @ApiResponses(value = {@ApiResponse(responseCode = "204", description = "SMTP Configuration updated successful."), @ApiResponse(responseCode = "400", description = "SMTP update failed.")}) + @ApiResponses(value = {@ApiResponse(responseCode = "204", description = "SMTP configuration updated successful."), @ApiResponse(responseCode = "400", description = "SMTP update failed.")}) void updateSMTPConfiguration(@RequestBody SMTPConfiguration smtpConfigurationModel); @@ -42,14 +42,14 @@ public interface SMTPConfigurationResource { @ResponseStatus(value = HttpStatus.OK) @PostMapping(value = SMTP_PATH + TEST_PATH, consumes = MediaType.APPLICATION_JSON_VALUE, produces = MediaType.APPLICATION_JSON_VALUE) @Operation(summary = "Test SMTP Settings to KeyCloak") - @ApiResponses(value = {@ApiResponse(responseCode = "200", description = "SMTP Configuration is valid."), @ApiResponse(responseCode = "400", description = "SMTP test failed.")}) + @ApiResponses(value = {@ApiResponse(responseCode = "200", description = "SMTP configuration is valid."), @ApiResponse(responseCode = "400", description = "SMTP test failed.")}) SMTPResponse testSMTPConfiguration(@RequestBody SMTPConfiguration smtpConfigurationModel); @ResponseStatus(value = HttpStatus.NO_CONTENT) @DeleteMapping(value = SMTP_PATH) - @Operation(summary = "Clear SMTP Settings to KeyCloak") - @ApiResponses(value = {@ApiResponse(responseCode = "200", description = "SMTP Configuration has been cleared."), @ApiResponse(responseCode = "400", description = "Failed to clear SMTP Configuration.")}) + @Operation(summary = "Deletes SMTP settings on KeyCloak") + @ApiResponses(value = {@ApiResponse(responseCode = "200", description = "SMTP configuration has been deleted."), @ApiResponse(responseCode = "400", description = "Failed to delete SMTP configuration.")}) void clearSMTPConfiguration(); } diff --git a/src/main/java/com/knecon/fforesight/tenantusermanagement/api/external/TenantsResource.java b/src/main/java/com/knecon/fforesight/tenantusermanagement/api/external/TenantsResource.java index bf605a1..0e528fd 100644 --- a/src/main/java/com/knecon/fforesight/tenantusermanagement/api/external/TenantsResource.java +++ b/src/main/java/com/knecon/fforesight/tenantusermanagement/api/external/TenantsResource.java @@ -28,19 +28,19 @@ public interface TenantsResource { @PostMapping(value = "/tenants", consumes = MediaType.APPLICATION_JSON_VALUE) - @Operation(summary = "Creates a new Tenant", description = "None") + @Operation(summary = "Create a new tenant", description = "None") @ApiResponses(value = {@ApiResponse(responseCode = "200", description = "OK")}) void createTenant(@RequestBody TenantRequest tenant); @GetMapping(value = "/tenants", produces = MediaType.APPLICATION_JSON_VALUE) - @Operation(summary = "Gets all existing tenant", description = "None") + @Operation(summary = "Gets all existing tenants", description = "None") @ApiResponses(value = {@ApiResponse(responseCode = "200", description = "OK")}) List getTenants(); @GetMapping(value = "/tenants/{tenantId}", produces = MediaType.APPLICATION_JSON_VALUE) - @Operation(summary = "Gets all existing tenant", description = "None") + @Operation(summary = "Gets an existing tenant", description = "None") @ApiResponses(value = {@ApiResponse(responseCode = "200", description = "OK")}) TenantResponse getTenant(@PathVariable("tenantId") String tenantId); @@ -50,7 +50,7 @@ public interface TenantsResource { TenantResponse updateTenant(@PathVariable("tenantId") String tenantId, @RequestBody TenantRequest tenantRequest); @GetMapping(value = "/tenants/simple", produces = MediaType.APPLICATION_JSON_VALUE) - @Operation(summary = "Gets all existing tenant in a simplified format", description = "None") + @Operation(summary = "Gets all existing tenants in a simplified format", description = "None") @ApiResponses(value = {@ApiResponse(responseCode = "200", description = "OK")}) List getSimpleTenants(); diff --git a/src/main/java/com/knecon/fforesight/tenantusermanagement/api/external/UserPreferenceResource.java b/src/main/java/com/knecon/fforesight/tenantusermanagement/api/external/UserPreferenceResource.java index 4a9b04e..54d54ea 100644 --- a/src/main/java/com/knecon/fforesight/tenantusermanagement/api/external/UserPreferenceResource.java +++ b/src/main/java/com/knecon/fforesight/tenantusermanagement/api/external/UserPreferenceResource.java @@ -28,14 +28,14 @@ public interface UserPreferenceResource { @ResponseBody @ResponseStatus(value = HttpStatus.OK) @GetMapping(value = PREFERENCES_PATH, produces = MediaType.APPLICATION_JSON_VALUE) - @Operation(summary = "Get User Attributes.", description = "None") + @Operation(summary = "Gets user attributes", description = "None") @ApiResponses(value = {@ApiResponse(responseCode = "200", description = "OK")}) Map> getAllUserAttributes(); @ResponseStatus(HttpStatus.NO_CONTENT) @PutMapping(value = PREFERENCES_PATH + KEY_PATH_VARIABLE, consumes = MediaType.APPLICATION_JSON_VALUE) - @Operation(summary = "Store User Attribute by key.", description = "None") + @Operation(summary = "Store user attribute by key", description = "None") @ApiResponses(value = {@ApiResponse(responseCode = "204", description = "OK")}) void setAttribute(@PathVariable(KEY_PARAMETER_NAME) String key, @RequestBody List values); @@ -43,7 +43,7 @@ public interface UserPreferenceResource { @ResponseBody @ResponseStatus(value = HttpStatus.NO_CONTENT) @DeleteMapping(value = PREFERENCES_PATH + KEY_PATH_VARIABLE) - @Operation(summary = "Delete User Preferences by key.", description = "None") + @Operation(summary = "Delete user preferences by key", description = "None") @ApiResponses(value = {@ApiResponse(responseCode = "204", description = "OK")}) void deleteAttribute(@PathVariable(KEY_PARAMETER_NAME) String key); diff --git a/src/main/java/com/knecon/fforesight/tenantusermanagement/api/external/UserResource.java b/src/main/java/com/knecon/fforesight/tenantusermanagement/api/external/UserResource.java index 84ddea6..68b3d33 100644 --- a/src/main/java/com/knecon/fforesight/tenantusermanagement/api/external/UserResource.java +++ b/src/main/java/com/knecon/fforesight/tenantusermanagement/api/external/UserResource.java @@ -45,22 +45,22 @@ public interface UserResource { @ResponseBody - @Operation(summary = "Gets the users who contain application-specific roles.", description = "None") - @ApiResponses(value = {@ApiResponse(responseCode = "200", description = "OK"), @ApiResponse(responseCode = "400", description = "Invalid " + "offset or limit specified.")}) + @Operation(summary = "Gets the users holding application-specific roles", description = "None") + @ApiResponses(value = {@ApiResponse(responseCode = "200", description = "OK"), @ApiResponse(responseCode = "400", description = "Invalid offset or limit specified.")}) @GetMapping(value = RED_USER_REST_PATH, produces = MediaType.APPLICATION_JSON_VALUE) List getApplicationSpecificUsers(@RequestParam(name = REFRESH_CACHE_PARAM, defaultValue = "false", required = false) boolean bypassCache); @ResponseBody - @Operation(summary = "Gets all the users in realm with information of roles.", description = "None") - @ApiResponses(value = {@ApiResponse(responseCode = "200", description = "OK"), @ApiResponse(responseCode = "400", description = "Invalid " + "offset or limit specified.")}) + @Operation(summary = "Gets all users in realm including role info", description = "None") + @ApiResponses(value = {@ApiResponse(responseCode = "200", description = "OK"), @ApiResponse(responseCode = "400", description = "Invalid offset or limit specified.")}) @GetMapping(value = USER_REST_PATH, produces = MediaType.APPLICATION_JSON_VALUE) List getAllUsers(@RequestParam(name = REFRESH_CACHE_PARAM, defaultValue = "false", required = false) boolean bypassCache); @ResponseBody @ResponseStatus(value = HttpStatus.OK) - @Operation(summary = "Update your own user-profile.", description = "None") + @Operation(summary = "Update a user profile", description = "None") @ApiResponses(value = {@ApiResponse(responseCode = "204", description = "OK"), @ApiResponse(responseCode = "400", description = "Failed to update profile, e-mail cannot be empty")}) @PostMapping(value = UPDATE_USER_PROFILE_PATH + USER_ID_PATH_VARIABLE, consumes = MediaType.APPLICATION_JSON_VALUE, produces = MediaType.APPLICATION_JSON_VALUE) User updateProfile(@PathVariable(USER_ID) String userId, @RequestBody UpdateProfileRequest updateProfileRequest); @@ -68,7 +68,7 @@ public interface UserResource { @ResponseBody @ResponseStatus(value = HttpStatus.OK) - @Operation(summary = "Update your own user-profile.", description = "None") + @Operation(summary = "Update your user profile", description = "None") @ApiResponses(value = {@ApiResponse(responseCode = "204", description = "OK"), @ApiResponse(responseCode = "400", description = "Failed to update profile, e-mail cannot be empty")}) @PostMapping(value = UPDATE_MY_USER_PROFILE_PATH, consumes = MediaType.APPLICATION_JSON_VALUE, produces = MediaType.APPLICATION_JSON_VALUE) User updateMyProfile(@RequestBody UpdateMyProfileRequest updateProfileRequest); @@ -91,35 +91,35 @@ public interface UserResource { @ResponseBody - @Operation(summary = "Create a new user.", description = "None") + @Operation(summary = "Create a new user", description = "None") @ApiResponses(value = {@ApiResponse(responseCode = "200", description = "OK"), @ApiResponse(responseCode = "400", description = "Invalid Data."), @ApiResponse(responseCode = "409", description = "User already exists.")}) @PostMapping(value = USER_REST_PATH, consumes = MediaType.APPLICATION_JSON_VALUE, produces = MediaType.APPLICATION_JSON_VALUE) User createUser(@RequestBody CreateUserRequest user); @ResponseBody - @Operation(summary = "Gets the user in realm with information of roles.", description = "None") - @ApiResponses(value = {@ApiResponse(responseCode = "200", description = "OK"), @ApiResponse(responseCode = "404", description = "The " + "userId can not be found."), @ApiResponse(responseCode = "400", description = "The provided user id is empty or " + "null.")}) + @Operation(summary = "Gets the user in realm including role info", description = "None") + @ApiResponses(value = {@ApiResponse(responseCode = "200", description = "OK"), @ApiResponse(responseCode = "404", description = "The " + "userId cannot be found."), @ApiResponse(responseCode = "400", description = "The provided user id is empty or " + "null.")}) @GetMapping(value = USER_REST_PATH + USER_ID_PATH_VARIABLE, produces = MediaType.APPLICATION_JSON_VALUE) User getUserById(@PathVariable(USER_ID) String userId); @ResponseStatus(value = HttpStatus.OK) - @Operation(summary = "Add a role to users", description = "None") - @ApiResponses(value = {@ApiResponse(responseCode = "204", description = "No Content"), @ApiResponse(responseCode = "404", description = "The provided userId can not be found."), @ApiResponse(responseCode = "400", description = "One ore more roles are not valid.")}) + @Operation(summary = "Add roles to a user", description = "None") + @ApiResponses(value = {@ApiResponse(responseCode = "204", description = "No Content"), @ApiResponse(responseCode = "404", description = "The provided userId cannot be found."), @ApiResponse(responseCode = "400", description = "One ore more roles are not valid.")}) @PostMapping(value = USER_ROLE_REST_PATH, consumes = MediaType.APPLICATION_JSON_VALUE, produces = MediaType.APPLICATION_JSON_VALUE) User setRoles(@PathVariable(USER_ID) String userId, @RequestBody Set roles); @ResponseStatus(value = HttpStatus.NO_CONTENT) @Operation(summary = "Reset a user's password", description = "None") - @ApiResponses(value = {@ApiResponse(responseCode = "204", description = "No Content"), @ApiResponse(responseCode = "404", description = "The provided userId can not be found.")}) + @ApiResponses(value = {@ApiResponse(responseCode = "204", description = "No Content"), @ApiResponse(responseCode = "404", description = "The provided userId cannot be found.")}) @PostMapping(value = RESET_PASSWORD_PATH, consumes = MediaType.APPLICATION_JSON_VALUE) void resetPassword(@PathVariable(USER_ID) String userId, @RequestBody ResetPasswordRequest resetPasswordRequest); @ResponseBody - @Operation(summary = "Activate/ deactivate a user-profile.", description = "None") + @Operation(summary = "Activate/deactivate a user profile", description = "None") @ApiResponses(value = {@ApiResponse(responseCode = "200", description = "OK"), @ApiResponse(responseCode = "400", description = "Failed to activate/deactivate profile")}) @PostMapping(value = ACTIVATE_USER_PROFILE_PATH + USER_ID_PATH_VARIABLE, produces = MediaType.APPLICATION_JSON_VALUE) User activateProfile(@PathVariable(USER_ID) String userId, @RequestParam(IS_ACTIVE_PARAM) boolean isActive); diff --git a/src/main/java/com/knecon/fforesight/tenantusermanagement/model/GeneralConfigurationModel.java b/src/main/java/com/knecon/fforesight/tenantusermanagement/model/GeneralConfigurationModel.java index 9dd759d..245f711 100644 --- a/src/main/java/com/knecon/fforesight/tenantusermanagement/model/GeneralConfigurationModel.java +++ b/src/main/java/com/knecon/fforesight/tenantusermanagement/model/GeneralConfigurationModel.java @@ -15,7 +15,7 @@ import lombok.NoArgsConstructor; @Schema(description = "Object containing data about general configurations.") public class GeneralConfigurationModel { - @Schema(description = "Parameter indicating if the function 'ForgotPassword' is enabled.") + @Schema(description = "Parameter indicating if the 'ForgotPassword' function is enabled.") private boolean forgotPasswordFunctionEnabled; @Schema(description = "Parameter containing the auxiliary name.") private String auxiliaryName; diff --git a/src/main/java/com/knecon/fforesight/tenantusermanagement/model/ResetPasswordRequest.java b/src/main/java/com/knecon/fforesight/tenantusermanagement/model/ResetPasswordRequest.java index 31dcd31..6b199ef 100644 --- a/src/main/java/com/knecon/fforesight/tenantusermanagement/model/ResetPasswordRequest.java +++ b/src/main/java/com/knecon/fforesight/tenantusermanagement/model/ResetPasswordRequest.java @@ -9,7 +9,7 @@ public class ResetPasswordRequest { @Schema(description = "Parameter containing the new password.") private String password; - @Schema(description = "Parameter indicating if the password id temporary.") + @Schema(description = "Parameter indicating if the password is temporary.") private boolean temporary; } diff --git a/src/main/java/com/knecon/fforesight/tenantusermanagement/model/TenantUser.java b/src/main/java/com/knecon/fforesight/tenantusermanagement/model/TenantUser.java index 4bfda6a..ae312a2 100644 --- a/src/main/java/com/knecon/fforesight/tenantusermanagement/model/TenantUser.java +++ b/src/main/java/com/knecon/fforesight/tenantusermanagement/model/TenantUser.java @@ -13,7 +13,7 @@ import lombok.NoArgsConstructor; @Builder @NoArgsConstructor @AllArgsConstructor -@Schema(description = "Object containing the data about a tenant user.") +@Schema(description = "Object containing the tenant user data.") public class TenantUser { @Schema(description = "Parameter containing the username of the tenant user.")