From d103b52228de3f510a5ad692b6a28fb49a944cc7 Mon Sep 17 00:00:00 2001 From: Eduard Heimbuch Date: Wed, 19 Feb 2020 13:02:01 +0100 Subject: [PATCH] update rest resource annotations --- .../v2/resources/GroupCollectionResource.java | 27 +++--- .../v2/resources/GroupPermissionResource.java | 3 - .../scm/api/v2/resources/GroupResource.java | 83 ++++++++++++------- .../api/v2/resources/GroupRootResource.java | 9 +- .../scm/api/v2/resources/IndexResource.java | 35 +++++++- 5 files changed, 99 insertions(+), 58 deletions(-) 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 854ddbfe58..2582c2e5f2 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 @@ -1,16 +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.OpenAPIDefinition; 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 io.swagger.v3.oas.annotations.tags.Tag; import sonia.scm.group.Group; import sonia.scm.group.GroupManager; import sonia.scm.search.SearchRequest; @@ -31,11 +26,8 @@ import java.util.function.Predicate; import static com.google.common.base.Strings.isNullOrEmpty; -@OpenAPIDefinition(tags = { - @Tag(name = "Group", description = "Group related endpoints") -}) public class GroupCollectionResource { - + private static final int DEFAULT_PAGE_SIZE = 10; private final GroupDtoToGroupMapper dtoToGroupMapper; private final GroupCollectionToDtoMapper groupCollectionToDtoMapper; @@ -85,18 +77,19 @@ public class GroupCollectionResource { ) ) public Response getAll(@DefaultValue("0") @QueryParam("page") int page, - @DefaultValue("" + DEFAULT_PAGE_SIZE) @QueryParam("pageSize") int pageSize, - @QueryParam("sortBy") String sortBy, - @DefaultValue("false") - @QueryParam("desc") boolean desc, - @DefaultValue("") @QueryParam("q") String search + @DefaultValue("" + DEFAULT_PAGE_SIZE) @QueryParam("pageSize") int pageSize, + @QueryParam("sortBy") String sortBy, + @DefaultValue("false") + @QueryParam("desc") boolean desc, + @DefaultValue("") @QueryParam("q") String search ) { return adapter.getAll(page, pageSize, createSearchPredicate(search), sortBy, desc, - pageResult -> groupCollectionToDtoMapper.map(page, pageSize, pageResult)); + pageResult -> groupCollectionToDtoMapper.map(page, pageSize, pageResult)); } /** * Creates a new group. + * * @param group The group to be created. * @return A response with the link to the new group (if created successfully). */ @@ -119,8 +112,8 @@ public class GroupCollectionResource { @ResponseHeaders(@ResponseHeader(name = "Location", description = "uri to the created group")) public Response create(@Valid GroupDto group) { return adapter.create(group, - () -> dtoToGroupMapper.map(group), - g -> resourceLinks.group().self(g.getName())); + () -> dtoToGroupMapper.map(group), + g -> resourceLinks.group().self(g.getName())); } private Predicate createSearchPredicate(String search) { 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 cc09783030..d18e5c9a95 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 @@ -1,8 +1,5 @@ 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; 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 cfc1916fc1..012620872e 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 @@ -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.group.Group; import sonia.scm.group.GroupManager; import sonia.scm.web.VndMediaType; @@ -40,20 +41,31 @@ public class GroupResource { * Note: This method requires "group" privilege. * * @param id the id/name of the group - * */ @GET @Path("") @Produces(VndMediaType.GROUP) - @TypeHint(GroupDto.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 group"), - @ResponseCode(code = 404, condition = "not found, no group with the specified id/name available"), - @ResponseCode(code = 500, condition = "internal server error") - }) - public Response get(@PathParam("id") String id){ + @Operation(summary = "Get single group", description = "Returns a group.", tags = "Group") + @ApiResponse( + responseCode = "200", + description = "success", + content = @Content( + mediaType = VndMediaType.GROUP, + schema = @Schema(implementation = GroupDto.class) + ) + ) + @ApiResponse(responseCode = "401", description = "not authenticated / invalid credentials") + @ApiResponse(responseCode = "403", description = "not authorized, the current user has no privileges to read the group") + @ApiResponse(responseCode = "404", description = "not found, no group 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 get(@PathParam("id") String id) { return adapter.get(id, groupToGroupDtoMapper::map); } @@ -63,17 +75,21 @@ public class GroupResource { * Note: This method requires "group" privilege. * * @param name the name of the group to delete. - * */ @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 \"group\" privilege"), - @ResponseCode(code = 500, condition = "internal server error") - }) - @TypeHint(TypeHint.NO_CONTENT.class) + @Operation(summary = "Delete group", description = "Deletes a group.", tags = "Group") + @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 has no privileges to read the group") + @ApiResponse( + responseCode = "500", + description = "internal server error", + content = @Content( + mediaType = VndMediaType.ERROR_TYPE, + schema = @Schema(implementation = ErrorDto.class) + ) + ) public Response delete(@PathParam("id") String name) { return adapter.delete(name); } @@ -83,21 +99,26 @@ public class GroupResource { * * Note: This method requires "group" privilege. * - * @param name name of the group to be modified + * @param name name of the group to be modified * @param group group object to modify */ @PUT @Path("") @Consumes(VndMediaType.GROUP) - @StatusCodes({ - @ResponseCode(code = 204, condition = "update success"), - @ResponseCode(code = 400, condition = "Invalid body, e.g. illegal change of id/group name"), - @ResponseCode(code = 401, condition = "not authenticated / invalid credentials"), - @ResponseCode(code = 403, condition = "not authorized, the current user does not have the \"group\" privilege"), - @ResponseCode(code = 404, condition = "not found, no group with the specified id/name available"), - @ResponseCode(code = 500, condition = "internal server error") - }) - @TypeHint(TypeHint.NO_CONTENT.class) + @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 = "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") + @ApiResponse( + responseCode = "500", + description = "internal server error", + content = @Content( + mediaType = VndMediaType.ERROR_TYPE, + schema = @Schema(implementation = ErrorDto.class) + ) + ) public Response update(@PathParam("id") String name, @Valid GroupDto group) { return adapter.update(name, existing -> dtoToGroupMapper.map(group)); } diff --git a/scm-webapp/src/main/java/sonia/scm/api/v2/resources/GroupRootResource.java b/scm-webapp/src/main/java/sonia/scm/api/v2/resources/GroupRootResource.java index ab11449ef2..6750dfef33 100644 --- a/scm-webapp/src/main/java/sonia/scm/api/v2/resources/GroupRootResource.java +++ b/scm-webapp/src/main/java/sonia/scm/api/v2/resources/GroupRootResource.java @@ -1,7 +1,7 @@ package sonia.scm.api.v2.resources; -import io.swagger.v3.oas.annotations.Hidden; -import io.swagger.v3.oas.annotations.Operation; +import io.swagger.v3.oas.annotations.OpenAPIDefinition; +import io.swagger.v3.oas.annotations.tags.Tag; import javax.inject.Inject; import javax.inject.Provider; @@ -10,6 +10,9 @@ import javax.ws.rs.Path; /** * RESTful Web Service Resource to manage groups and their members. */ +@OpenAPIDefinition(tags = { + @Tag(name = "Group", description = "Group related endpoints") +}) @Path(GroupRootResource.GROUPS_PATH_V2) public class GroupRootResource { @@ -20,7 +23,7 @@ public class GroupRootResource { @Inject public GroupRootResource(Provider groupCollectionResource, - Provider groupResource) { + Provider groupResource) { this.groupCollectionResource = groupCollectionResource; this.groupResource = groupResource; } diff --git a/scm-webapp/src/main/java/sonia/scm/api/v2/resources/IndexResource.java b/scm-webapp/src/main/java/sonia/scm/api/v2/resources/IndexResource.java index 611fba6f2c..cf482edd11 100644 --- a/scm-webapp/src/main/java/sonia/scm/api/v2/resources/IndexResource.java +++ b/scm-webapp/src/main/java/sonia/scm/api/v2/resources/IndexResource.java @@ -2,7 +2,12 @@ package sonia.scm.api.v2.resources; import com.webcohesion.enunciate.metadata.rs.TypeHint; import io.swagger.v3.oas.annotations.OpenAPIDefinition; +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 io.swagger.v3.oas.annotations.security.SecurityRequirement; +import io.swagger.v3.oas.annotations.tags.Tag; import sonia.scm.security.AllowAnonymousAccess; import sonia.scm.web.VndMediaType; @@ -11,10 +16,15 @@ import javax.ws.rs.GET; import javax.ws.rs.Path; import javax.ws.rs.Produces; -@OpenAPIDefinition(security = { - @SecurityRequirement(name = "Basic Authentication"), - @SecurityRequirement(name = "Bearer Token Authentication") -}) +@OpenAPIDefinition( + security = { + @SecurityRequirement(name = "Basic Authentication"), + @SecurityRequirement(name = "Bearer Token Authentication") + }, + tags = { + @Tag(name = "Index", description = "SCM-Manager Index") + } +) @Path(IndexResource.INDEX_PATH_V2) @AllowAnonymousAccess public class IndexResource { @@ -30,6 +40,23 @@ public class IndexResource { @GET @Path("") @Produces(VndMediaType.INDEX) + @Operation(summary = "Get index", description = "Returns the index for the scm-manager instance.", tags = "Index") + @ApiResponse( + responseCode = "200", + description = "success", + content = @Content( + mediaType = VndMediaType.INDEX, + schema = @Schema(implementation = IndexDto.class) + ) + ) + @ApiResponse( + responseCode = "500", + description = "internal server error", + content = @Content( + mediaType = VndMediaType.ERROR_TYPE, + schema = @Schema(implementation = ErrorDto.class) + ) + ) @TypeHint(IndexDto.class) public IndexDto getIndex() { return indexDtoGenerator.generate();