From 6ea21f01ef10f32576f6dc88a121b5c8abdd22cf Mon Sep 17 00:00:00 2001 From: Florian Scholdei Date: Wed, 19 Feb 2020 13:51:54 +0100 Subject: [PATCH] Update rest resource annotations --- .../v2/resources/AuthenticationResource.java | 4 +- .../api/v2/resources/DiffRootResource.java | 4 +- .../resources/GlobalPermissionResource.java | 2 +- .../v2/resources/GroupCollectionResource.java | 4 +- .../v2/resources/GroupPermissionResource.java | 2 +- .../scm/api/v2/resources/GroupResource.java | 2 +- .../api/v2/resources/RepositoryResource.java | 2 +- .../v2/resources/RepositoryRoleResource.java | 2 +- .../v2/resources/UserCollectionResource.java | 54 +++++++---- .../v2/resources/UserPermissionResource.java | 64 ++++++++---- .../scm/api/v2/resources/UserResource.java | 97 ++++++++++++------- .../api/v2/resources/UserRootResource.java | 6 ++ 12 files changed, 156 insertions(+), 87 deletions(-) diff --git a/scm-webapp/src/main/java/sonia/scm/api/v2/resources/AuthenticationResource.java b/scm-webapp/src/main/java/sonia/scm/api/v2/resources/AuthenticationResource.java index 370eaf84b4..1c55b54fb1 100644 --- a/scm-webapp/src/main/java/sonia/scm/api/v2/resources/AuthenticationResource.java +++ b/scm-webapp/src/main/java/sonia/scm/api/v2/resources/AuthenticationResource.java @@ -81,7 +81,7 @@ public class AuthenticationResource { @POST @Path("access_token") @Consumes(MediaType.APPLICATION_FORM_URLENCODED) - @Operation(summary = "Login via Form", description = "Form-based authentication", tags = "Authentication") + @Operation(summary = "Login via Form", description = "Form-based authentication.", tags = "Authentication") @ApiResponse(responseCode = "200", description = "success") @ApiResponse(responseCode = "400", description = "bad request, required parameter is missing") @ApiResponse(responseCode = "401", description = "unauthorized, the specified username or password is wrong") @@ -104,7 +104,7 @@ public class AuthenticationResource { @POST @Path("access_token") @Consumes(MediaType.APPLICATION_JSON) - @Operation(summary = "Login via JSON", description = "JSON-based authentication", tags = "Authentication") + @Operation(summary = "Login via JSON", description = "JSON-based authentication.", tags = "Authentication") @ApiResponse(responseCode = "200", description = "success") @ApiResponse(responseCode = "400", description = "bad request, required parameter is missing") @ApiResponse(responseCode = "401", description = "unauthorized, the specified username or password is wrong") diff --git a/scm-webapp/src/main/java/sonia/scm/api/v2/resources/DiffRootResource.java b/scm-webapp/src/main/java/sonia/scm/api/v2/resources/DiffRootResource.java index b73c0d7d64..6124cab10b 100644 --- a/scm-webapp/src/main/java/sonia/scm/api/v2/resources/DiffRootResource.java +++ b/scm-webapp/src/main/java/sonia/scm/api/v2/resources/DiffRootResource.java @@ -56,7 +56,7 @@ public class DiffRootResource { @Produces(VndMediaType.DIFF) @Operation(summary = "Diff by revision", description = "Get the repository diff of a revision.", tags = "Repository") @ApiResponse(responseCode = "200", description = "success") - @ApiResponse(responseCode = "400", description = "Bad Request") + @ApiResponse(responseCode = "400", description = "bad request") @ApiResponse(responseCode = "401", description = "not authenticated / invalid credentials") @ApiResponse(responseCode = "403", description = "not authorized, the current user has no privileges to read the diff") @ApiResponse(responseCode = "404", description = "not found, no revision with the specified param for the repository available or repository not found") @@ -94,7 +94,7 @@ public class DiffRootResource { schema = @Schema(implementation = DiffResultDto.class) ) ) - @ApiResponse(responseCode = "400", description = "Bad Request") + @ApiResponse(responseCode = "400", description = "bad request") @ApiResponse(responseCode = "401", description = "not authenticated / invalid credentials") @ApiResponse(responseCode = "403", description = "not authorized, the current user has no privileges to read the diff") @ApiResponse(responseCode = "404", description = "not found, no revision with the specified param for the repository available or repository not found") diff --git a/scm-webapp/src/main/java/sonia/scm/api/v2/resources/GlobalPermissionResource.java b/scm-webapp/src/main/java/sonia/scm/api/v2/resources/GlobalPermissionResource.java index 7045fbb1a2..79cfbb51b8 100644 --- a/scm-webapp/src/main/java/sonia/scm/api/v2/resources/GlobalPermissionResource.java +++ b/scm-webapp/src/main/java/sonia/scm/api/v2/resources/GlobalPermissionResource.java @@ -31,7 +31,7 @@ public class GlobalPermissionResource { @GET @Produces(VndMediaType.PERMISSION_COLLECTION) - @Operation(summary = "List of permissions", description = "Returns all available permissions", tags = "Permissions") + @Operation(summary = "List of permissions", description = "Returns all available permissions.", tags = "Permissions") @ApiResponse( responseCode = "200", description = "success", diff --git a/scm-webapp/src/main/java/sonia/scm/api/v2/resources/GroupCollectionResource.java b/scm-webapp/src/main/java/sonia/scm/api/v2/resources/GroupCollectionResource.java index 2582c2e5f2..cfb498dcb3 100644 --- a/scm-webapp/src/main/java/sonia/scm/api/v2/resources/GroupCollectionResource.java +++ b/scm-webapp/src/main/java/sonia/scm/api/v2/resources/GroupCollectionResource.java @@ -56,7 +56,7 @@ public class GroupCollectionResource { @GET @Path("") @Produces(VndMediaType.GROUP_COLLECTION) - @Operation(summary = "List of groups", description = "Returns all groups for a given page number", tags = "Group") + @Operation(summary = "List of groups", description = "Returns all groups for a given page number with a given page size.", tags = "Group") @ApiResponse( responseCode = "200", description = "success", @@ -96,7 +96,7 @@ public class GroupCollectionResource { @POST @Path("") @Consumes(VndMediaType.GROUP) - @Operation(summary = "Create group", description = "Creates a new group", tags = "Group") + @Operation(summary = "Create group", description = "Creates a new group.", tags = "Group") @ApiResponse(responseCode = "201", description = "create success") @ApiResponse(responseCode = "401", description = "not authenticated / invalid credentials") @ApiResponse(responseCode = "403", description = "not authorized, the current user does not have the \"group\" privilege") diff --git a/scm-webapp/src/main/java/sonia/scm/api/v2/resources/GroupPermissionResource.java b/scm-webapp/src/main/java/sonia/scm/api/v2/resources/GroupPermissionResource.java index d18e5c9a95..b00719abbe 100644 --- a/scm-webapp/src/main/java/sonia/scm/api/v2/resources/GroupPermissionResource.java +++ b/scm-webapp/src/main/java/sonia/scm/api/v2/resources/GroupPermissionResource.java @@ -76,7 +76,7 @@ public class GroupPermissionResource { @Consumes(VndMediaType.PERMISSION_COLLECTION) @Operation(summary = "Update Group permissions", description = "Sets permissions for a group. Overwrites all existing permissions.", tags = {"Group", "Permissions"}) @ApiResponse(responseCode = "204", description = "update success") - @ApiResponse(responseCode = "400", description = "Invalid body") + @ApiResponse(responseCode = "400", description = "invalid body") @ApiResponse(responseCode = "401", description = "not authenticated / invalid credentials") @ApiResponse(responseCode = "403", description = "not authorized, the current group does not have the correct privilege") @ApiResponse(responseCode = "404", description = "not found, no group with the specified id/name available") diff --git a/scm-webapp/src/main/java/sonia/scm/api/v2/resources/GroupResource.java b/scm-webapp/src/main/java/sonia/scm/api/v2/resources/GroupResource.java index 012620872e..510657c797 100644 --- a/scm-webapp/src/main/java/sonia/scm/api/v2/resources/GroupResource.java +++ b/scm-webapp/src/main/java/sonia/scm/api/v2/resources/GroupResource.java @@ -107,7 +107,7 @@ public class GroupResource { @Consumes(VndMediaType.GROUP) @Operation(summary = "Update group", description = "Modifies a group.", tags = "Group") @ApiResponse(responseCode = "204", description = "update success") - @ApiResponse(responseCode = "400", description = "Invalid body, e.g. illegal change of id/group name") + @ApiResponse(responseCode = "400", description = "invalid body, e.g. illegal change of id/group name") @ApiResponse(responseCode = "401", description = "not authenticated / invalid credentials") @ApiResponse(responseCode = "403", description = "not authorized, the current user does not have the \"group\" privilege") @ApiResponse(responseCode = "404", description = "not found, no group with the specified id/name available") diff --git a/scm-webapp/src/main/java/sonia/scm/api/v2/resources/RepositoryResource.java b/scm-webapp/src/main/java/sonia/scm/api/v2/resources/RepositoryResource.java index ebae9e53e9..8eb1c204a7 100644 --- a/scm-webapp/src/main/java/sonia/scm/api/v2/resources/RepositoryResource.java +++ b/scm-webapp/src/main/java/sonia/scm/api/v2/resources/RepositoryResource.java @@ -164,7 +164,7 @@ public class RepositoryResource { @Consumes(VndMediaType.REPOSITORY) @StatusCodes({ @ResponseCode(code = 204, condition = "update success"), - @ResponseCode(code = 400, condition = "Invalid body, e.g. illegal change of namespace or name"), + @ResponseCode(code = 400, condition = "invalid body, e.g. illegal change of namespace or name"), @ResponseCode(code = 401, condition = "not authenticated / invalid credentials"), @ResponseCode(code = 403, condition = "not authorized, the current user does not have the \"repository\" privilege"), @ResponseCode(code = 404, condition = "not found, no repository with the specified namespace and name available"), diff --git a/scm-webapp/src/main/java/sonia/scm/api/v2/resources/RepositoryRoleResource.java b/scm-webapp/src/main/java/sonia/scm/api/v2/resources/RepositoryRoleResource.java index 59adbce264..3a85fb5377 100644 --- a/scm-webapp/src/main/java/sonia/scm/api/v2/resources/RepositoryRoleResource.java +++ b/scm-webapp/src/main/java/sonia/scm/api/v2/resources/RepositoryRoleResource.java @@ -90,7 +90,7 @@ public class RepositoryRoleResource { @Consumes(VndMediaType.REPOSITORY_ROLE) @StatusCodes({ @ResponseCode(code = 204, condition = "update success"), - @ResponseCode(code = 400, condition = "Invalid body, e.g. illegal change of repository role name"), + @ResponseCode(code = 400, condition = "invalid body, e.g. illegal change of repository role name"), @ResponseCode(code = 401, condition = "not authenticated / invalid credentials"), @ResponseCode(code = 403, condition = "not authorized, the current user does not have the \"repositoryRole\" privilege"), @ResponseCode(code = 404, condition = "not found, no repository role with the specified name available"), diff --git a/scm-webapp/src/main/java/sonia/scm/api/v2/resources/UserCollectionResource.java b/scm-webapp/src/main/java/sonia/scm/api/v2/resources/UserCollectionResource.java index 3e35b8d4a6..72c0a534ef 100644 --- a/scm-webapp/src/main/java/sonia/scm/api/v2/resources/UserCollectionResource.java +++ b/scm-webapp/src/main/java/sonia/scm/api/v2/resources/UserCollectionResource.java @@ -1,10 +1,11 @@ package sonia.scm.api.v2.resources; -import com.webcohesion.enunciate.metadata.rs.ResponseCode; import com.webcohesion.enunciate.metadata.rs.ResponseHeader; import com.webcohesion.enunciate.metadata.rs.ResponseHeaders; -import com.webcohesion.enunciate.metadata.rs.StatusCodes; -import com.webcohesion.enunciate.metadata.rs.TypeHint; +import io.swagger.v3.oas.annotations.Operation; +import io.swagger.v3.oas.annotations.media.Content; +import io.swagger.v3.oas.annotations.media.Schema; +import io.swagger.v3.oas.annotations.responses.ApiResponse; import org.apache.shiro.authc.credential.PasswordService; import sonia.scm.search.SearchRequest; import sonia.scm.search.SearchUtil; @@ -59,14 +60,25 @@ public class UserCollectionResource { @GET @Path("") @Produces(VndMediaType.USER_COLLECTION) - @TypeHint(CollectionDto.class) - @StatusCodes({ - @ResponseCode(code = 200, condition = "success"), - @ResponseCode(code = 400, condition = "\"sortBy\" field unknown"), - @ResponseCode(code = 401, condition = "not authenticated / invalid credentials"), - @ResponseCode(code = 403, condition = "not authorized, the current user does not have the \"user\" privilege"), - @ResponseCode(code = 500, condition = "internal server error") - }) + @Operation(summary = "List of users", description = "Returns all users for a given page number with a given page size.", tags = "User") + @ApiResponse( + responseCode = "200", + description = "success", + content = @Content( + mediaType = VndMediaType.USER_COLLECTION, + schema = @Schema(implementation = CollectionDto.class) + ) + ) + @ApiResponse(responseCode = "400", description = "\"sortBy\" field unknown") + @ApiResponse(responseCode = "401", description = "not authenticated / invalid credentials") + @ApiResponse(responseCode = "403", description = "not authorized, the current user does not have the \"user\" privilege") + @ApiResponse( + responseCode = "500", + description = "internal server error", + content = @Content( + mediaType = VndMediaType.ERROR_TYPE, + schema = @Schema(implementation = ErrorDto.class) + )) public Response getAll(@DefaultValue("0") @QueryParam("page") int page, @DefaultValue("" + DEFAULT_PAGE_SIZE) @QueryParam("pageSize") int pageSize, @QueryParam("sortBy") String sortBy, @@ -88,14 +100,18 @@ public class UserCollectionResource { @POST @Path("") @Consumes(VndMediaType.USER) - @StatusCodes({ - @ResponseCode(code = 201, condition = "create success"), - @ResponseCode(code = 401, condition = "not authenticated / invalid credentials"), - @ResponseCode(code = 403, condition = "not authorized, the current user does not have the \"user\" privilege"), - @ResponseCode(code = 409, condition = "conflict, a user with this name already exists"), - @ResponseCode(code = 500, condition = "internal server error") - }) - @TypeHint(TypeHint.NO_CONTENT.class) + @Operation(summary = "Create user", description = "Creates a new user.", tags = "User") + @ApiResponse(responseCode = "201", description = "create success") + @ApiResponse(responseCode = "401", description = "not authenticated / invalid credentials") + @ApiResponse(responseCode = "403", description = "not authorized, the current user does not have the \"user\" privilege") + @ApiResponse(responseCode = "409", description = "conflict, a user with this name already exists") + @ApiResponse( + responseCode = "500", + description = "internal server error", + content = @Content( + mediaType = VndMediaType.ERROR_TYPE, + schema = @Schema(implementation = ErrorDto.class) + )) @ResponseHeaders(@ResponseHeader(name = "Location", description = "uri to the created user")) public Response create(@Valid UserDto user) { return adapter.create(user, () -> dtoToUserMapper.map(user, passwordService.encryptPassword(user.getPassword())), u -> resourceLinks.user().self(u.getName())); diff --git a/scm-webapp/src/main/java/sonia/scm/api/v2/resources/UserPermissionResource.java b/scm-webapp/src/main/java/sonia/scm/api/v2/resources/UserPermissionResource.java index fd54da503d..bf8ff4b3c1 100644 --- a/scm-webapp/src/main/java/sonia/scm/api/v2/resources/UserPermissionResource.java +++ b/scm-webapp/src/main/java/sonia/scm/api/v2/resources/UserPermissionResource.java @@ -1,8 +1,9 @@ package sonia.scm.api.v2.resources; -import com.webcohesion.enunciate.metadata.rs.ResponseCode; -import com.webcohesion.enunciate.metadata.rs.StatusCodes; -import com.webcohesion.enunciate.metadata.rs.TypeHint; +import io.swagger.v3.oas.annotations.Operation; +import io.swagger.v3.oas.annotations.media.Content; +import io.swagger.v3.oas.annotations.media.Schema; +import io.swagger.v3.oas.annotations.responses.ApiResponse; import sonia.scm.security.PermissionAssigner; import sonia.scm.security.PermissionDescriptor; import sonia.scm.security.PermissionPermissions; @@ -40,14 +41,32 @@ public class UserPermissionResource { @GET @Path("") @Produces(VndMediaType.PERMISSION_COLLECTION) - @TypeHint(PermissionListDto.class) - @StatusCodes({ - @ResponseCode(code = 200, condition = "success"), - @ResponseCode(code = 401, condition = "not authenticated / invalid credentials"), - @ResponseCode(code = 403, condition = "not authorized, the current user has no privileges to read the user"), - @ResponseCode(code = 404, condition = "not found, no user with the specified id/name available"), - @ResponseCode(code = 500, condition = "internal server error") - }) + @Operation(summary = "User permission", description = "Returns the global git configuration.", tags = {"User", "Permissions"}) + @ApiResponse( + responseCode = "200", + description = "success", + content = @Content( + mediaType = VndMediaType.PERMISSION_COLLECTION, + schema = @Schema(implementation = PermissionListDto.class) + ) + ) + @ApiResponse(responseCode = "401", description = "not authenticated / invalid credentials") + @ApiResponse(responseCode = "403", description = "not authorized, the current user has no privileges to read the user") + @ApiResponse( + responseCode = "404", + description = "not found, no user with the specified id/name available", + content = @Content( + mediaType = VndMediaType.ERROR_TYPE, + schema = @Schema(implementation = ErrorDto.class) + ) + ) + @ApiResponse( + responseCode = "500", + description = "internal server error", + content = @Content( + mediaType = VndMediaType.ERROR_TYPE, + schema = @Schema(implementation = ErrorDto.class) + )) public Response getPermissions(@PathParam("id") String id) { PermissionPermissions.read().check(); Collection permissions = permissionAssigner.readPermissionsForUser(id); @@ -63,15 +82,20 @@ public class UserPermissionResource { @PUT @Path("") @Consumes(VndMediaType.PERMISSION_COLLECTION) - @StatusCodes({ - @ResponseCode(code = 204, condition = "update success"), - @ResponseCode(code = 400, condition = "Invalid body"), - @ResponseCode(code = 401, condition = "not authenticated / invalid credentials"), - @ResponseCode(code = 403, condition = "not authorized, the current user does not have the correct privilege"), - @ResponseCode(code = 404, condition = "not found, no user with the specified id/name available"), - @ResponseCode(code = 500, condition = "internal server error") - }) - @TypeHint(TypeHint.NO_CONTENT.class) + @Operation(summary = "Update user permissions", description = "Sets permissions for a user. Overwrites all existing permissions.", tags = {"User", "Permissions"}) + @ApiResponse(responseCode = "204", description = "update success") + @ApiResponse(responseCode = "400", description = "invalid body") + @ApiResponse(responseCode = "401", description = "not authenticated / invalid credentials") + @ApiResponse(responseCode = "403", description = "not authorized, the current user does not have the correct privilege") + @ApiResponse(responseCode = "404", description = "not found, no user with the specified id/name available") + @ApiResponse( + responseCode = "500", + description = "internal server error", + content = @Content( + mediaType = VndMediaType.ERROR_TYPE, + schema = @Schema(implementation = ErrorDto.class) + ) + ) public Response overwritePermissions(@PathParam("id") String id, @Valid PermissionListDto newPermissions) { Collection permissionDescriptors = Arrays.stream(newPermissions.getPermissions()) .map(PermissionDescriptor::new) diff --git a/scm-webapp/src/main/java/sonia/scm/api/v2/resources/UserResource.java b/scm-webapp/src/main/java/sonia/scm/api/v2/resources/UserResource.java index e2a6cc797e..016eb27430 100644 --- a/scm-webapp/src/main/java/sonia/scm/api/v2/resources/UserResource.java +++ b/scm-webapp/src/main/java/sonia/scm/api/v2/resources/UserResource.java @@ -1,12 +1,12 @@ package sonia.scm.api.v2.resources; -import com.webcohesion.enunciate.metadata.rs.ResponseCode; -import com.webcohesion.enunciate.metadata.rs.StatusCodes; -import com.webcohesion.enunciate.metadata.rs.TypeHint; +import io.swagger.v3.oas.annotations.Operation; +import io.swagger.v3.oas.annotations.media.Content; +import io.swagger.v3.oas.annotations.media.Schema; +import io.swagger.v3.oas.annotations.responses.ApiResponse; import org.apache.shiro.authc.credential.PasswordService; import sonia.scm.user.User; import sonia.scm.user.UserManager; -import sonia.scm.user.UserPermissions; import sonia.scm.web.VndMediaType; import javax.inject.Inject; @@ -54,14 +54,31 @@ public class UserResource { @GET @Path("") @Produces(VndMediaType.USER) - @TypeHint(UserDto.class) - @StatusCodes({ - @ResponseCode(code = 200, condition = "success"), - @ResponseCode(code = 401, condition = "not authenticated / invalid credentials"), - @ResponseCode(code = 403, condition = "not authorized, the current user has no privileges to read the user"), - @ResponseCode(code = 404, condition = "not found, no user with the specified id/name available"), - @ResponseCode(code = 500, condition = "internal server error") - }) + @Operation(summary = "Returns a single user", description = "Returns the user for the given id.", tags = "User") + @ApiResponse( + responseCode = "200", + description = "success", + content = @Content( + mediaType = VndMediaType.USER, + schema = @Schema(implementation = UserDto.class) + ) + ) + @ApiResponse(responseCode = "401", description = "not authenticated / invalid credentials") + @ApiResponse(responseCode = "403", description = "not authorized, the current user has no privileges to read the user") + @ApiResponse( + responseCode = "404", + description = "not found, no user with the specified id/name available", + content = @Content( + mediaType = VndMediaType.ERROR_TYPE, + schema = @Schema(implementation = ErrorDto.class) + )) + @ApiResponse( + responseCode = "500", + description = "internal server error", + content = @Content( + mediaType = VndMediaType.ERROR_TYPE, + schema = @Schema(implementation = ErrorDto.class) + )) public Response get(@PathParam("id") String id) { return adapter.get(id, userToDtoMapper::map); } @@ -75,13 +92,11 @@ public class UserResource { */ @DELETE @Path("") - @StatusCodes({ - @ResponseCode(code = 204, condition = "delete success or nothing to delete"), - @ResponseCode(code = 401, condition = "not authenticated / invalid credentials"), - @ResponseCode(code = 403, condition = "not authorized, the current user does not have the \"user\" privilege"), - @ResponseCode(code = 500, condition = "internal server error") - }) - @TypeHint(TypeHint.NO_CONTENT.class) + @Operation(summary = "Deletes a user", description = "Deletes the user for the given id.", tags = "User") + @ApiResponse(responseCode = "204", description = "delete success or nothing to delete") + @ApiResponse(responseCode = "401", description = "not authenticated / invalid credentials") + @ApiResponse(responseCode = "403", description = "not authorized, the current user does not have the \"user\" privilege") + @ApiResponse(responseCode = "500", description = "internal server error") public Response delete(@PathParam("id") String name) { return adapter.delete(name); } @@ -98,15 +113,19 @@ public class UserResource { @PUT @Path("") @Consumes(VndMediaType.USER) - @StatusCodes({ - @ResponseCode(code = 204, condition = "update success"), - @ResponseCode(code = 400, condition = "Invalid body, e.g. illegal change of id/user name"), - @ResponseCode(code = 401, condition = "not authenticated / invalid credentials"), - @ResponseCode(code = 403, condition = "not authorized, the current user does not have the \"user\" privilege"), - @ResponseCode(code = 404, condition = "not found, no user with the specified id/name available"), - @ResponseCode(code = 500, condition = "internal server error") - }) - @TypeHint(TypeHint.NO_CONTENT.class) + @Operation(summary = "Modifies a user", description = "Modifies the user for the given id.", tags = "User") + @ApiResponse(responseCode = "204", description = "update success") + @ApiResponse(responseCode = "400", description = "invalid body, e.g. illegal change of id/user name") + @ApiResponse(responseCode = "401", description = "not authenticated / invalid credentials") + @ApiResponse(responseCode = "403", description = "not authorized, the current user does not have the \"user\" privilege") + @ApiResponse( + responseCode = "404", + description = "not found, no user with the specified id/name available", + content = @Content( + mediaType = VndMediaType.ERROR_TYPE, + schema = @Schema(implementation = ErrorDto.class) + )) + @ApiResponse(responseCode = "500", description = "internal server error") public Response update(@PathParam("id") String name, @Valid UserDto user) { return adapter.update(name, existing -> dtoToUserMapper.map(user, existing.getPassword())); } @@ -125,15 +144,19 @@ public class UserResource { @PUT @Path("password") @Consumes(VndMediaType.PASSWORD_OVERWRITE) - @StatusCodes({ - @ResponseCode(code = 204, condition = "update success"), - @ResponseCode(code = 400, condition = "Invalid body, e.g. the user type is not xml or the given oldPassword do not match the stored one"), - @ResponseCode(code = 401, condition = "not authenticated / invalid credentials"), - @ResponseCode(code = 403, condition = "not authorized, the current user does not have the \"user\" privilege"), - @ResponseCode(code = 404, condition = "not found, no user with the specified id/name available"), - @ResponseCode(code = 500, condition = "internal server error") - }) - @TypeHint(TypeHint.NO_CONTENT.class) + @Operation(summary = "Modifies a user password", description = "Lets admins modifies the user password for the given id.", tags = "User") + @ApiResponse(responseCode = "204", description = "update success") + @ApiResponse(responseCode = "400", description = "invalid body, e.g. the user type is not xml or the given oldPassword do not match the stored one") + @ApiResponse(responseCode = "401", description = "not authenticated / invalid credentials") + @ApiResponse(responseCode = "403", description = "not authorized, the current user does not have the \"user\" privilege") + @ApiResponse( + responseCode = "404", + description = "not found, no user with the specified id/name available", + content = @Content( + mediaType = VndMediaType.ERROR_TYPE, + schema = @Schema(implementation = ErrorDto.class) + )) + @ApiResponse(responseCode = "500", description = "internal server error") public Response overwritePassword(@PathParam("id") String name, @Valid PasswordOverwriteDto passwordOverwrite) { userManager.overwritePassword(name, passwordService.encryptPassword(passwordOverwrite.getNewPassword())); return Response.noContent().build(); diff --git a/scm-webapp/src/main/java/sonia/scm/api/v2/resources/UserRootResource.java b/scm-webapp/src/main/java/sonia/scm/api/v2/resources/UserRootResource.java index 9652a97404..a358597238 100644 --- a/scm-webapp/src/main/java/sonia/scm/api/v2/resources/UserRootResource.java +++ b/scm-webapp/src/main/java/sonia/scm/api/v2/resources/UserRootResource.java @@ -1,5 +1,8 @@ package sonia.scm.api.v2.resources; +import io.swagger.v3.oas.annotations.OpenAPIDefinition; +import io.swagger.v3.oas.annotations.tags.Tag; + import javax.inject.Inject; import javax.inject.Provider; import javax.ws.rs.Path; @@ -7,6 +10,9 @@ import javax.ws.rs.Path; /** * RESTful Web Service Resource to manage users. */ +@OpenAPIDefinition(tags = { + @Tag(name = "User", description = "User related endpoints") +}) @Path(UserRootResource.USERS_PATH_V2) public class UserRootResource {