FINERACT-1222: Add Swagger tags for User Administration

fineract-provider/src/main/java/org/apache/fineract/useradministration/api/PasswordPreferencesApiResource.java

@@ -67,6 +67,8 @@ public class PasswordPreferencesApiResource {
     @Produces({ MediaType.APPLICATION_JSON })
     @ApiResponses({
             @ApiResponse(responseCode = "200", description = "OK", content = @Content(schema = @Schema(implementation = PasswordPreferencesApiResourceSwagger.GetPasswordPreferencesTemplateResponse.class))) })
+    @Operation(summary = "List Password Preferences", description = "Returns the password policies and their current status (active/inactive).", tags = {
+            "Password preferences" })
     public String retrieve(@Context final UriInfo uriInfo) {
 
         this.context.authenticatedUser().validateHasReadPermission(PasswordPreferencesApiConstants.ENTITY_NAME);
@@ -82,7 +84,7 @@ public String retrieve(@Context final UriInfo uriInfo) {
     @PUT
     @Consumes({ MediaType.APPLICATION_JSON })
     @Produces({ MediaType.APPLICATION_JSON })
-    @Operation(summary = "Update password preferences", description = "")
+    @Operation(summary = "Update password preferences", tags = { "Password preferences" }, description = "")
     @RequestBody(required = true, content = @Content(schema = @Schema(implementation = PasswordPreferencesApiResourceSwagger.PutPasswordPreferencesTemplateRequest.class)))
     @ApiResponses({ @ApiResponse(responseCode = "200", description = "OK") })
     public String update(@Parameter(hidden = true) final String apiRequestBodyAsJson) {
@@ -100,8 +102,8 @@ public String update(@Parameter(hidden = true) final String apiRequestBodyAsJson
     @GET
     @Path("/template")
     @Produces({ MediaType.APPLICATION_JSON })
-    @Operation(summary = "List Application Password validation policies", description = "ARGUMENTS\n" + "Example Requests:\n" + "\n"
-            + "passwordpreferences")
+    @Operation(summary = "List Application Password validation policies", tags = { "Password preferences" }, description = "ARGUMENTS\n"
+            + "Example Requests:\n" + "\n" + "passwordpreferences")
     @ApiResponses({
             @ApiResponse(responseCode = "200", description = "OK", content = @Content(array = @ArraySchema(schema = @Schema(implementation = PasswordPreferencesApiResourceSwagger.GetPasswordPreferencesTemplateResponse.class)))) })
     public String template(@Context final UriInfo uriInfo) {

fineract-provider/src/main/java/org/apache/fineract/useradministration/api/PermissionsApiResource.java

@@ -72,7 +72,7 @@ public class PermissionsApiResource {
 
     @GET
     @Produces({ MediaType.APPLICATION_JSON })
-    @Operation(summary = "List Application Permissions", description = "ARGUMENTS\n"
+    @Operation(summary = "List Application Permissions", tags = { "Permissions" }, description = "ARGUMENTS\n"
             + "makerCheckerableoptional, Values are true, false. Default is false.\n"
             + "If makerCheckerable=false or not supplied then a list of application permissions is returned. The \"selected\" attribute is always true in this case.\n"
             + "\n"
@@ -100,7 +100,7 @@ public String retrieveAllPermissions(@Context final UriInfo uriInfo) {
     @PUT
     @Consumes({ MediaType.APPLICATION_JSON })
     @Produces({ MediaType.APPLICATION_JSON })
-    @Operation(summary = "Enable/Disable Permissions for Maker Checker", description = "")
+    @Operation(summary = "Enable/Disable Permissions for Maker Checker", tags = { "Permissions" }, description = "")
     @RequestBody(required = true, content = @Content(schema = @Schema(implementation = PermissionsApiResourceSwagger.PutPermissionsRequest.class)))
     @ApiResponses({
             @ApiResponse(responseCode = "200", description = "OK", content = @Content(schema = @Schema(implementation = CommandProcessingResult.class))) })

fineract-provider/src/main/java/org/apache/fineract/useradministration/api/RolesApiResource.java

@@ -97,7 +97,8 @@ public class RolesApiResource {
 
     @GET
     @Produces({ MediaType.APPLICATION_JSON })
-    @Operation(summary = "List Roles", description = "Example Requests:\n" + "\n" + "roles\n" + "\n" + "\n" + "roles?fields=name")
+    @Operation(summary = "List Roles", tags = { "Roles" }, description = "Example Requests:\n" + "\n" + "roles\n" + "\n" + "\n"
+            + "roles?fields=name")
     @ApiResponses({
             @ApiResponse(responseCode = "200", description = "OK", content = @Content(array = @ArraySchema(schema = @Schema(implementation = RolesApiResourceSwagger.GetRolesResponse.class)))) })
     public String retrieveAllRoles(@Context final UriInfo uriInfo) {
@@ -113,7 +114,7 @@ public String retrieveAllRoles(@Context final UriInfo uriInfo) {
     @POST
     @Consumes({ MediaType.APPLICATION_JSON })
     @Produces({ MediaType.APPLICATION_JSON })
-    @Operation(summary = "Create a New Role", description = "Mandatory Fields\n" + "name, description")
+    @Operation(summary = "Create a New Role", tags = { "Roles" }, description = "Mandatory Fields\n" + "name, description")
     @RequestBody(required = true, content = @Content(schema = @Schema(implementation = RolesApiResourceSwagger.PostRolesRequest.class)))
     @ApiResponses({
             @ApiResponse(responseCode = "200", description = "OK", content = @Content(schema = @Schema(implementation = RolesApiResourceSwagger.PostRolesResponse.class))) })
@@ -132,7 +133,8 @@ public String createRole(@Parameter(hidden = true) final String apiRequestBodyAs
     @GET
     @Path("{roleId}")
     @Produces({ MediaType.APPLICATION_JSON })
-    @Operation(summary = "Retrieve a Role", description = "Example Requests:\n" + "\n" + "roles/1\n" + "\n" + "\n" + "roles/1?fields=name")
+    @Operation(summary = "Retrieve a Role", tags = { "Roles" }, description = "Example Requests:\n" + "\n" + "roles/1\n" + "\n" + "\n"
+            + "roles/1?fields=name")
     @ApiResponses({
             @ApiResponse(responseCode = "200", description = "OK", content = @Content(schema = @Schema(implementation = RolesApiResourceSwagger.GetRolesRoleIdResponse.class))) })
     public String retrieveRole(@PathParam("roleId") @Parameter(description = "roleId") final Long roleId, @Context final UriInfo uriInfo) {
@@ -158,9 +160,10 @@ public String retrieveRole(@PathParam("roleId") @Parameter(description = "roleId
     @Path("{roleId}")
     @Consumes({ MediaType.APPLICATION_JSON })
     @Produces({ MediaType.APPLICATION_JSON })
-    @Operation(summary = "Enable Role | Disable Role", description = "Description : Enable role in case role is disabled. | Disable the role in case role is not associated with any users.\n\n\n\n"
-            + "\n\n" + "Example Request:   https://DomainName/api/v1/roles/{roleId}?command=enable" + "\n\n\n\n" + "\n\n"
-            + "https://DomainName/api/v1/roles/{roleId}?command=disable")
+    @Operation(summary = "Enable Role | Disable Role", tags = {
+            "Roles" }, description = "Description : Enable role in case role is disabled. | Disable the role in case role is not associated with any users.\n\n\n\n"
+                    + "\n\n" + "Example Request:   https://DomainName/api/v1/roles/{roleId}?command=enable" + "\n\n\n\n" + "\n\n"
+                    + "https://DomainName/api/v1/roles/{roleId}?command=disable")
     @Parameters({ @Parameter(description = "No Request Body", name = "No Request Body") })
     @ApiResponses({
             @ApiResponse(responseCode = "200", description = "OK", content = @Content(schema = @Schema(implementation = RolesApiResourceSwagger.PostRolesRoleIdResponse.class))) })
@@ -186,7 +189,7 @@ public String actionsOnRoles(@PathParam("roleId") @Parameter(description = "role
     @Path("{roleId}")
     @Consumes({ MediaType.APPLICATION_JSON })
     @Produces({ MediaType.APPLICATION_JSON })
-    @Operation(summary = "Update a Role", description = "")
+    @Operation(summary = "Update a Role", tags = { "Roles" }, description = "")
     @RequestBody(required = true, content = @Content(schema = @Schema(implementation = RolesApiResourceSwagger.PutRolesRoleIdRequest.class)))
     @ApiResponses({
             @ApiResponse(responseCode = "200", description = "OK", content = @Content(schema = @Schema(implementation = RolesApiResourceSwagger.PutRolesRoleIdResponse.class))) })
@@ -206,7 +209,8 @@ public String updateRole(@PathParam("roleId") @Parameter(description = "roleId")
     @GET
     @Path("{roleId}/permissions")
     @Produces({ MediaType.APPLICATION_JSON })
-    @Operation(summary = "Retrieve a Role's Permissions", description = "Example Requests:\n" + "\n" + "roles/1/permissions")
+    @Operation(summary = "Retrieve a Role's Permissions", tags = { "Roles" }, description = "Example Requests:\n" + "\n"
+            + "roles/1/permissions")
     @ApiResponses({
             @ApiResponse(responseCode = "200", description = "OK", content = @Content(schema = @Schema(implementation = RolesApiResourceSwagger.GetRolesRoleIdPermissionsResponse.class))) })
     public String retrieveRolePermissions(@PathParam("roleId") @Parameter(description = "roleId") final Long roleId,
@@ -226,7 +230,7 @@ public String retrieveRolePermissions(@PathParam("roleId") @Parameter(descriptio
     @Path("{roleId}/permissions")
     @Consumes({ MediaType.APPLICATION_JSON })
     @Produces({ MediaType.APPLICATION_JSON })
-    @Operation(summary = "Update a Role's Permissions", description = "")
+    @Operation(summary = "Update a Role's Permissions", tags = { "Roles" }, description = "")
     @RequestBody(required = true, content = @Content(schema = @Schema(implementation = RolesApiResourceSwagger.PutRolesRoleIdPermissionsRequest.class)))
     @ApiResponses({
             @ApiResponse(responseCode = "200", description = "OK", content = @Content(schema = @Schema(implementation = RolesApiResourceSwagger.PutRolesRoleIdPermissionsResponse.class))) })
@@ -252,7 +256,8 @@ public String updateRolePermissions(@PathParam("roleId") @Parameter(description
     @DELETE
     @Path("{roleId}")
     @Produces({ MediaType.APPLICATION_JSON })
-    @Operation(summary = "Delete a Role", description = "Description : Delete the role in case role is not associated with any users.")
+    @Operation(summary = "Delete a Role", tags = {
+            "Roles" }, description = "Description : Delete the role in case role is not associated with any users.")
     @ApiResponses({
             @ApiResponse(responseCode = "200", description = "OK", content = @Content(schema = @Schema(implementation = RolesApiResourceSwagger.DeleteRolesRoleIdResponse.class))) })
     public String deleteRole(@PathParam("roleId") @Parameter(description = "roleId") final Long roleId) {

fineract-provider/src/main/java/org/apache/fineract/useradministration/api/UsersApiResource.java

@@ -90,8 +90,8 @@ public class UsersApiResource {
     private final BulkImportWorkbookService bulkImportWorkbookService;
 
     @GET
-    @Operation(summary = "Retrieve list of users", operationId = "retrieveAllUsers", description = "Example Requests:\n" + "\n" + "users\n"
-            + "\n" + "\n" + "users?fields=id,username,email,officeName")
+    @Operation(summary = "Retrieve list of users", operationId = "retrieveAllUsers", tags = { "Users" }, description = "Example Requests:\n"
+            + "\n" + "users\n" + "\n" + "\n" + "users?fields=id,username,email,officeName")
     @ApiResponses({
             @ApiResponse(responseCode = "200", description = "OK", content = @Content(array = @ArraySchema(schema = @Schema(implementation = UsersApiResourceSwagger.GetUsersResponse.class)))) })
     @Produces({ MediaType.APPLICATION_JSON })
@@ -107,8 +107,8 @@ public String retrieveAll(@Context final UriInfo uriInfo) {
 
     @GET
     @Path("{userId}")
-    @Operation(summary = "Retrieve a User", operationId = "retrieveOneUser", description = "Example Requests:\n" + "\n" + "users/1\n" + "\n"
-            + "\n" + "users/1?template=true\n" + "\n" + "\n" + "users/1?fields=username,officeName")
+    @Operation(summary = "Retrieve a User", operationId = "retrieveOneUser", tags = { "Users" }, description = "Example Requests:\n" + "\n"
+            + "users/1\n" + "\n" + "\n" + "users/1?template=true\n" + "\n" + "\n" + "users/1?fields=username,officeName")
     @ApiResponses({
             @ApiResponse(responseCode = "200", description = "OK", content = @Content(schema = @Schema(implementation = UsersApiResourceSwagger.GetUsersUserIdResponse.class))) })
     @Produces({ MediaType.APPLICATION_JSON })
@@ -129,8 +129,9 @@ public String retrieveOne(@PathParam("userId") @Parameter(description = "userId"
 
     @GET
     @Path("template")
-    @Operation(summary = "Retrieve User Details Template", operationId = "retrieveTemplateUser", description = "This is a convenience resource. It can be useful when building maintenance user interface screens for client applications. The template data returned consists of any or all of:\n"
-            + "\n" + "Field Defaults\n" + "Allowed description Lists\n" + "Example Request:\n" + "\n" + "users/template")
+    @Operation(summary = "Retrieve User Details Template", operationId = "retrieveTemplateUser", tags = {
+            "Users" }, description = "This is a convenience resource. It can be useful when building maintenance user interface screens for client applications. The template data returned consists of any or all of:\n"
+                    + "\n" + "Field Defaults\n" + "Allowed description Lists\n" + "Example Request:\n" + "\n" + "users/template")
     @ApiResponses({
             @ApiResponse(responseCode = "200", description = "OK", content = @Content(schema = @Schema(implementation = UsersApiResourceSwagger.GetUsersTemplateResponse.class))) })
     @Produces({ MediaType.APPLICATION_JSON })
@@ -145,10 +146,11 @@ public String template(@Context final UriInfo uriInfo) {
     }
 
     @POST
-    @Operation(summary = "Create a User", operationId = "createUser", description = "Adds new application user.\n" + "\n"
+    @Operation(summary = "Create a User", operationId = "createUser", tags = { "Users" }, description = "Adds new application user.\n"
+            + "\n"
             + "Note: Password information is not required (or processed). Password details at present are auto-generated and then sent to the email account given (which is why it can take a few seconds to complete).\n"
             + "\n" + "Mandatory Fields: \n" + "username, firstname, lastname, email, officeId, roles, sendPasswordToEmail\n" + "\n"
-            + "Optional Fields: \n" + "staffId,passwordNeverExpires,isLoginRetriesEnabled,isPasswordResetAllowed")
+            + "Optional Fields: \n" + "staffId,passwordNeverExpires,isLoginRetriesEnabled")
     @RequestBody(required = true, content = @Content(schema = @Schema(implementation = UsersApiResourceSwagger.PostUsersRequest.class)))
     @ApiResponses({
             @ApiResponse(responseCode = "200", description = "OK", content = @Content(schema = @Schema(implementation = UsersApiResourceSwagger.PostUsersResponse.class))) })
@@ -168,7 +170,7 @@ public String create(@Parameter(hidden = true) final String apiRequestBodyAsJson
 
     @PUT
     @Path("{userId}")
-    @Operation(summary = "Update a User", operationId = "updateUser", description = "Updates the user")
+    @Operation(summary = "Update a User", operationId = "updateUser", tags = { "Users" }, description = "Updates the user")
     @RequestBody(required = true, content = @Content(schema = @Schema(implementation = UsersApiResourceSwagger.PutUsersUserIdRequest.class)))
     @ApiResponses({
             @ApiResponse(responseCode = "200", description = "OK", content = @Content(schema = @Schema(implementation = UsersApiResourceSwagger.PutUsersUserIdResponse.class))) })
@@ -189,7 +191,8 @@ public String update(@PathParam("userId") @Parameter(description = "userId") fin
 
     @POST
     @Path("{userId}/pwd")
-    @Operation(summary = "Change the password of a User", operationId = "changePasswordUser", description = "When updating a password you must provide the repeatPassword parameter also.")
+    @Operation(summary = "Change the password of a User", operationId = "changePasswordUser", tags = {
+            "Users" }, description = "When updating a password you must provide the repeatPassword parameter also.")
     @RequestBody(required = true, content = @Content(schema = @Schema(implementation = UsersApiResourceSwagger.ChangePwdUsersUserIdRequest.class)))
     @ApiResponses({
             @ApiResponse(responseCode = "200", description = "OK", content = @Content(schema = @Schema(implementation = UsersApiResourceSwagger.ChangePwdUsersUserIdResponse.class))) })
@@ -210,7 +213,8 @@ public String changePassword(@PathParam("userId") @Parameter(description = "user
 
     @DELETE
     @Path("{userId}")
-    @Operation(summary = "Delete a User", operationId = "deleteUser", description = "Removes the user and the associated roles and permissions.")
+    @Operation(summary = "Delete a User", operationId = "deleteUser", tags = {
+            "Users" }, description = "Removes the user and the associated roles and permissions.")
     @ApiResponses({
             @ApiResponse(responseCode = "200", description = "OK", content = @Content(schema = @Schema(implementation = UsersApiResourceSwagger.DeleteUsersUserIdResponse.class))) })
     @Produces({ MediaType.APPLICATION_JSON })
@@ -228,6 +232,7 @@ public String delete(@PathParam("userId") @Parameter(description = "userId") fin
     @GET
     @Path("downloadtemplate")
     @Produces("application/vnd.ms-excel")
+    @Operation(summary = "Download users template", description = "Returns an Excel template for bulk importing users.", tags = { "Users" })
     public Response getUserTemplate(@QueryParam("officeId") final Long officeId, @QueryParam("staffId") final Long staffId,
             @QueryParam("dateFormat") final String dateFormat) {
         return bulkImportWorkbookPopulatorService.getTemplate(GlobalEntityType.USERS.toString(), officeId, staffId, dateFormat);
@@ -238,6 +243,8 @@ public Response getUserTemplate(@QueryParam("officeId") final Long officeId, @Qu
     @Consumes(MediaType.MULTIPART_FORM_DATA)
     @RequestBody(description = "Upload users template", content = {
             @Content(mediaType = MediaType.MULTIPART_FORM_DATA, schema = @Schema(implementation = UploadRequest.class)) })
+    @Operation(summary = "Upload users template", description = "Uploads a filled Excel template to create multiple users in bulk.", tags = {
+            "Users" })
     public String postUsersTemplate(@FormDataParam("file") InputStream uploadedInputStream,
             @FormDataParam("file") FormDataContentDisposition fileDetail, @FormDataParam("locale") final String locale,
             @FormDataParam("dateFormat") final String dateFormat) {