diff --git a/scm-webapp/src/main/java/sonia/scm/api/v2/resources/CreateGroupDto.java b/scm-webapp/src/main/java/sonia/scm/api/v2/resources/CreateGroupDto.java new file mode 100644 index 0000000000..bc1324e0f1 --- /dev/null +++ b/scm-webapp/src/main/java/sonia/scm/api/v2/resources/CreateGroupDto.java @@ -0,0 +1,49 @@ +/* + * MIT License + * + * Copyright (c) 2020-present Cloudogu GmbH and Contributors + * + * Permission is hereby granted, free of charge, to any person obtaining a copy + * of this software and associated documentation files (the "Software"), to deal + * in the Software without restriction, including without limitation the rights + * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell + * copies of the Software, and to permit persons to whom the Software is + * furnished to do so, subject to the following conditions: + * + * The above copyright notice and this permission notice shall be included in all + * copies or substantial portions of the Software. + * + * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE + * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, + * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE + * SOFTWARE. + */ + +package sonia.scm.api.v2.resources; + +import lombok.Getter; +import lombok.NoArgsConstructor; +import lombok.Setter; +import sonia.scm.util.ValidationUtil; + +import javax.validation.constraints.Pattern; +import java.util.List; + +/** + * This class is currently only used in the openapi scheme + */ +@Getter +@Setter +@NoArgsConstructor +public class CreateGroupDto { + + @Pattern(regexp = ValidationUtil.REGEX_NAME) + private String name; + private String description; + private String type; + private List members; + private boolean external; +} 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 e7f4ce4e85..90ee95148d 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 @@ -27,7 +27,9 @@ package sonia.scm.api.v2.resources; import io.swagger.v3.oas.annotations.Operation; import io.swagger.v3.oas.annotations.headers.Header; import io.swagger.v3.oas.annotations.media.Content; +import io.swagger.v3.oas.annotations.media.ExampleObject; import io.swagger.v3.oas.annotations.media.Schema; +import io.swagger.v3.oas.annotations.parameters.RequestBody; import io.swagger.v3.oas.annotations.responses.ApiResponse; import sonia.scm.group.Group; import sonia.scm.group.GroupManager; @@ -121,7 +123,30 @@ public class GroupCollectionResource { @POST @Path("") @Consumes(VndMediaType.GROUP) - @Operation(summary = "Create group", description = "Creates a new group.", tags = "Group", operationId = "group_create") + @Operation( + summary = "Create group", + description = "Creates a new group.", + tags = "Group", + operationId = "group_create", + requestBody = @RequestBody( + content = @Content( + mediaType = VndMediaType.GROUP, + schema = @Schema(implementation = CreateGroupDto.class), + examples = { + @ExampleObject( + name = "Create an group with a description", + value = "{\n \"name\":\"manager\",\n \"description\":\"Manager group with full read access\"\n}", + summary = "Create a simple group" + ), + @ExampleObject( + name = "Create an internal group with two members", + value = "{\n \"name\":\"Admins\",\n \"description\":\"SCM-Manager admins\",\n \"external\":false,\n \"members\":[\"scmadmin\",\"c.body\"]\n}", + summary = "Create group with members" + ) + } + ) + ) + ) @ApiResponse( responseCode = "201", description = "create success", 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 9e31ecfecb..9847b0558e 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 @@ -26,7 +26,9 @@ package sonia.scm.api.v2.resources; import io.swagger.v3.oas.annotations.Operation; import io.swagger.v3.oas.annotations.media.Content; +import io.swagger.v3.oas.annotations.media.ExampleObject; import io.swagger.v3.oas.annotations.media.Schema; +import io.swagger.v3.oas.annotations.parameters.RequestBody; import io.swagger.v3.oas.annotations.responses.ApiResponse; import sonia.scm.security.PermissionAssigner; import sonia.scm.security.PermissionDescriptor; @@ -104,7 +106,22 @@ public class GroupPermissionResource { @PUT @Path("") @Consumes(VndMediaType.PERMISSION_COLLECTION) - @Operation(summary = "Update Group permissions", description = "Sets permissions for a group. Overwrites all existing permissions.", tags = {"Group", "Permissions"}) + @Operation( + summary = "Update Group permissions", + description = "Sets permissions for a group. Overwrites all existing permissions.", + tags = {"Group", "Permissions"}, + requestBody = @RequestBody( + content = @Content( + mediaType = VndMediaType.PERMISSION_COLLECTION, + schema = @Schema(implementation = PermissionListDto.class), + examples = @ExampleObject( + name = "Add read permissions for all repositories and pull requests", + value = "{\n \"permissions\":[\"repository:read,pull:*\",\"repository:readPullRequest:*\"]\n}", + summary = "Simple update group permissions" + ) + ) + ) + ) @ApiResponse(responseCode = "204", description = "update success") @ApiResponse(responseCode = "400", description = "invalid body") @ApiResponse(responseCode = "401", description = "not authenticated / invalid credentials") @@ -116,6 +133,7 @@ public class GroupPermissionResource { mediaType = VndMediaType.ERROR_TYPE, schema = @Schema(implementation = ErrorDto.class) )) + @ApiResponse(responseCode = "409", description = "conflict, group has been modified concurrently") @ApiResponse( responseCode = "500", description = "internal server error", 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 4d0cd1738b..f3fea99bff 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 @@ -26,7 +26,9 @@ package sonia.scm.api.v2.resources; import io.swagger.v3.oas.annotations.Operation; import io.swagger.v3.oas.annotations.media.Content; +import io.swagger.v3.oas.annotations.media.ExampleObject; import io.swagger.v3.oas.annotations.media.Schema; +import io.swagger.v3.oas.annotations.parameters.RequestBody; import io.swagger.v3.oas.annotations.responses.ApiResponse; import sonia.scm.group.Group; import sonia.scm.group.GroupManager; @@ -135,7 +137,22 @@ public class GroupResource { @PUT @Path("") @Consumes(VndMediaType.GROUP) - @Operation(summary = "Update group", description = "Modifies a group.", tags = "Group") + @Operation( + summary = "Update group", + description = "Modifies a group.", + tags = "Group", + requestBody = @RequestBody( + content = @Content( + mediaType = VndMediaType.GROUP, + schema = @Schema(implementation = UpdateGroupDto.class), + examples = @ExampleObject( + name = "Update a group description", + value = "{\n \"name\":\"manager\",\n \"description\":\"Group of managers with full read access\",\n \"lastModified\":\"2020-06-05T14:42:49.000Z\",\n \"type\":\"xml\"\n}", + summary = "Update a 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") @@ -147,6 +164,7 @@ public class GroupResource { mediaType = VndMediaType.ERROR_TYPE, schema = @Schema(implementation = ErrorDto.class) )) + @ApiResponse(responseCode = "409", description = "conflict, group has been modified concurrently") @ApiResponse( responseCode = "500", description = "internal server error", diff --git a/scm-webapp/src/main/java/sonia/scm/api/v2/resources/UpdateGroupDto.java b/scm-webapp/src/main/java/sonia/scm/api/v2/resources/UpdateGroupDto.java new file mode 100644 index 0000000000..d9f06eb88b --- /dev/null +++ b/scm-webapp/src/main/java/sonia/scm/api/v2/resources/UpdateGroupDto.java @@ -0,0 +1,53 @@ +/* + * MIT License + * + * Copyright (c) 2020-present Cloudogu GmbH and Contributors + * + * Permission is hereby granted, free of charge, to any person obtaining a copy + * of this software and associated documentation files (the "Software"), to deal + * in the Software without restriction, including without limitation the rights + * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell + * copies of the Software, and to permit persons to whom the Software is + * furnished to do so, subject to the following conditions: + * + * The above copyright notice and this permission notice shall be included in all + * copies or substantial portions of the Software. + * + * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE + * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, + * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE + * SOFTWARE. + */ + +package sonia.scm.api.v2.resources; + +import com.fasterxml.jackson.annotation.JsonInclude; +import lombok.Getter; +import lombok.NoArgsConstructor; +import lombok.Setter; +import sonia.scm.util.ValidationUtil; + +import javax.validation.constraints.Pattern; +import java.time.Instant; +import java.util.List; + +/** + * This class is currently only used in the openapi scheme + */ +@Getter +@Setter +@NoArgsConstructor +public class UpdateGroupDto { + + @Pattern(regexp = ValidationUtil.REGEX_NAME) + private String name; + private String description; + @JsonInclude(JsonInclude.Include.NON_NULL) + private Instant lastModified; + private String type; + private List members; + private boolean external; +}