update rest resource annotations

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,9 +26,6 @@ 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;
@@ -97,6 +89,7 @@ public class GroupCollectionResource {
 
   /**
    * Creates a new group.
+   *
    * @param group The group to be created.
    * @return A response with the link to the new group (if created successfully).
    */

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;

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 io.swagger.v3.oas.annotations.Operation;
-import com.webcohesion.enunciate.metadata.rs.StatusCodes;
+import io.swagger.v3.oas.annotations.media.Content;
-import com.webcohesion.enunciate.metadata.rs.TypeHint;
+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 {
    * <strong>Note:</strong> This method requires "group" privilege.
    *
    * @param id the id/name of the group
-   *
    */
   @GET
   @Path("")
   @Produces(VndMediaType.GROUP)
-  @TypeHint(GroupDto.class)
+  @Operation(summary = "Get single group", description = "Returns a group.", tags = "Group")
-  @StatusCodes({
+  @ApiResponse(
-    @ResponseCode(code = 200, condition = "success"),
+    responseCode = "200",
-    @ResponseCode(code = 401, condition = "not authenticated / invalid credentials"),
+    description = "success",
-    @ResponseCode(code = 403, condition = "not authorized, the current user has no privileges to read the group"),
+    content = @Content(
-    @ResponseCode(code = 404, condition = "not found, no group with the specified id/name available"),
+      mediaType = VndMediaType.GROUP,
-    @ResponseCode(code = 500, condition = "internal server error")
+      schema = @Schema(implementation = GroupDto.class)
-  })
+    )
-  public Response get(@PathParam("id") String id){
+  )
+  @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 {
    * <strong>Note:</strong> This method requires "group" privilege.
    *
    * @param name the name of the group to delete.
-   *
    */
   @DELETE
   @Path("")
-  @StatusCodes({
+  @Operation(summary = "Delete group", description = "Deletes a group.", tags = "Group")
-    @ResponseCode(code = 204, condition = "delete success or nothing to delete"),
+  @ApiResponse(responseCode = "204", description = "delete success or nothing to delete")
-    @ResponseCode(code = 401, condition = "not authenticated / invalid credentials"),
+  @ApiResponse(responseCode = "401", description = "not authenticated / invalid credentials")
-    @ResponseCode(code = 403, condition = "not authorized, the current user does not have the \"group\" privilege"),
+  @ApiResponse(responseCode = "403", description = "not authorized, the current user has no privileges to read the group")
-    @ResponseCode(code = 500, condition = "internal server error")
+  @ApiResponse(
-  })
+    responseCode = "500",
-  @TypeHint(TypeHint.NO_CONTENT.class)
+    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);
   }
@@ -89,15 +105,20 @@ public class GroupResource {
   @PUT
   @Path("")
   @Consumes(VndMediaType.GROUP)
-  @StatusCodes({
+  @Operation(summary = "Update group", description = "Modifies a group.", tags = "Group")
-    @ResponseCode(code = 204, condition = "update success"),
+  @ApiResponse(responseCode = "204", description = "update success")
-    @ResponseCode(code = 400, condition = "Invalid body, e.g. illegal change of id/group name"),
+  @ApiResponse(responseCode = "400", description = "Invalid body, e.g. illegal change of id/group name")
-    @ResponseCode(code = 401, condition = "not authenticated / invalid credentials"),
+  @ApiResponse(responseCode = "401", description = "not authenticated / invalid credentials")
-    @ResponseCode(code = 403, condition = "not authorized, the current user does not have the \"group\" privilege"),
+  @ApiResponse(responseCode = "403", description = "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"),
+  @ApiResponse(responseCode = "404", description = "not found, no group with the specified id/name available")
-    @ResponseCode(code = 500, condition = "internal server error")
+  @ApiResponse(
-  })
+    responseCode = "500",
-  @TypeHint(TypeHint.NO_CONTENT.class)
+    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));
   }

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.OpenAPIDefinition;
-import io.swagger.v3.oas.annotations.Operation;
+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 {
 

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 = {
+@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();