Add examples for group resources

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",

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",

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",