From 59eb9de80b3a5f26e13317fc452c230c7bcbc7ad Mon Sep 17 00:00:00 2001 From: Florian Scholdei Date: Tue, 10 Nov 2020 17:23:12 +0100 Subject: [PATCH] Add examples for group resources --- .../v2/resources/GroupCollectionResource.java | 27 ++++++++++++++++++- .../v2/resources/GroupPermissionResource.java | 20 +++++++++++++- .../scm/api/v2/resources/GroupResource.java | 20 +++++++++++++- 3 files changed, 64 insertions(+), 3 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 e7f4ce4e85..9e4a070926 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 = GroupDto.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..0acb40c4bc 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 = GroupDto.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",