Update rest resource annotations

2025-11-12 16:35:45 +01:00 · 2020-02-19 16:51:20 +01:00
parent 154426ddd6
commit cbd86e8e5c
19 changed files with 653 additions and 319 deletions
--- a/scm-webapp/src/main/java/sonia/scm/api/v2/resources/BranchRootResource.java
+++ b/scm-webapp/src/main/java/sonia/scm/api/v2/resources/BranchRootResource.java
@@ -1,11 +1,12 @@
 package sonia.scm.api.v2.resources;

 import com.google.common.base.Strings;
-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.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.PageResult;
 import sonia.scm.repository.Branch;
 import sonia.scm.repository.Branches;
@@ -69,15 +70,27 @@ public class BranchRootResource {
  @GET
  @Path("{branch}")
  @Produces(VndMediaType.BRANCH)
-  @TypeHint(BranchDto.class)
-  @StatusCodes({
-    @ResponseCode(code = 200, condition = "success"),
-    @ResponseCode(code = 400, condition = "branches not supported for given repository"),
-    @ResponseCode(code = 401, condition = "not authenticated / invalid credentials"),
-    @ResponseCode(code = 403, condition = "not authorized, the current user has no privileges to read the branch"),
-    @ResponseCode(code = 404, condition = "not found, no branch with the specified name for the repository available or repository not found"),
-    @ResponseCode(code = 500, condition = "internal server error")
-  })
+  @Operation(summary = "Get single branch", description = "Returns a branch for a repository.", tags = "Repository")
+  @ApiResponse(
+    responseCode = "200",
+    description = "success",
+    content = @Content(
+      mediaType = VndMediaType.BRANCH,
+      schema = @Schema(implementation = BranchDto.class)
+    )
+  )
+  @ApiResponse(responseCode = "400", description = "branches not supported for given repository")
+  @ApiResponse(responseCode = "401", description = "not authenticated / invalid credentials")
+  @ApiResponse(responseCode = "403", description = "not authorized, the current user has no privileges to read the branch")
+  @ApiResponse(responseCode = "404", description = "not found, no branch with the specified name for the repository available or repository not found")
+  @ApiResponse(
+    responseCode = "500",
+    description = "internal server error",
+    content = @Content(
+      mediaType = VndMediaType.ERROR_TYPE,
+      schema = @Schema(implementation = ErrorDto.class)
+    )
+  )
  public Response get(@PathParam("namespace") String namespace, @PathParam("name") String name, @PathParam("branch") String branchName) throws IOException {
    NamespaceAndName namespaceAndName = new NamespaceAndName(namespace, name);
    try (RepositoryService repositoryService = serviceFactory.create(namespaceAndName)) {
@@ -95,17 +108,29 @@ public class BranchRootResource {
    }
  }

-  @Path("{branch}/changesets/")
  @GET
-  @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 changeset"),
-    @ResponseCode(code = 404, condition = "not found, no changesets available in the repository"),
-    @ResponseCode(code = 500, condition = "internal server error")
-  })
+  @Path("{branch}/changesets/")
  @Produces(VndMediaType.CHANGESET_COLLECTION)
-  @TypeHint(CollectionDto.class)
+  @Operation(summary = "Collection of changesets", description = "Returns a collection of changesets for specific branch.", tags = "Repository")
+  @ApiResponse(
+    responseCode = "200",
+    description = "success",
+    content = @Content(
+      mediaType = VndMediaType.CHANGESET_COLLECTION,
+      schema = @Schema(implementation = CollectionDto.class)
+    )
+  )
+  @ApiResponse(responseCode = "401", description = "not authenticated / invalid credentials")
+  @ApiResponse(responseCode = "403", description = "not authorized, the current user has no privileges to read the changeset")
+  @ApiResponse(responseCode = "404", description = "not found, no changesets available in the repository")
+  @ApiResponse(
+    responseCode = "500",
+    description = "internal server error",
+    content = @Content(
+      mediaType = VndMediaType.ERROR_TYPE,
+      schema = @Schema(implementation = ErrorDto.class)
+    )
+  )
  public Response history(@PathParam("namespace") String namespace,
                          @PathParam("name") String name,
                          @PathParam("branch") String branchName,
@@ -143,14 +168,18 @@ public class BranchRootResource {
  @POST
  @Path("")
  @Consumes(VndMediaType.BRANCH_REQUEST)
-  @StatusCodes({
-    @ResponseCode(code = 201, condition = "create success"),
-    @ResponseCode(code = 401, condition = "not authenticated / invalid credentials"),
-    @ResponseCode(code = 403, condition = "not authorized, the current user does not have the \"push\" privilege"),
-    @ResponseCode(code = 409, condition = "conflict, a user with this name already exists"),
-    @ResponseCode(code = 500, condition = "internal server error")
-  })
-  @TypeHint(TypeHint.NO_CONTENT.class)
+  @Operation(summary = "Create branch", description = "Creates a new branch.", tags = "Repository")
+  @ApiResponse(responseCode = "201", description = "create success")
+  @ApiResponse(responseCode = "401", description = "not authenticated / invalid credentials")
+  @ApiResponse(responseCode = "403", description = "not authorized, the current user does not have the \"push\" privilege")
+  @ApiResponse(responseCode = "409", description = "conflict, a branch with this name already exists")
+  @ApiResponse(
+    responseCode = "500",
+    description = "internal server error",
+    content = @Content(
+      mediaType = VndMediaType.ERROR_TYPE,
+      schema = @Schema(implementation = ErrorDto.class)
+    ))
  @ResponseHeaders(@ResponseHeader(name = "Location", description = "uri to the created branch"))
  public Response create(@PathParam("namespace") String namespace,
                         @PathParam("name") String name,
@@ -195,15 +224,33 @@ public class BranchRootResource {
  @GET
  @Path("")
  @Produces(VndMediaType.BRANCH_COLLECTION)
-  @TypeHint(CollectionDto.class)
-  @StatusCodes({
-    @ResponseCode(code = 200, condition = "success"),
-    @ResponseCode(code = 400, condition = "branches not supported for given repository"),
-    @ResponseCode(code = 401, condition = "not authenticated / invalid credentials"),
-    @ResponseCode(code = 403, condition = "not authorized, the current user does not have the \"read repository\" privilege"),
-    @ResponseCode(code = 404, condition = "not found, no repository found for the given namespace and name"),
-    @ResponseCode(code = 500, condition = "internal server error")
-  })
+  @Operation(summary = "List of branches", description = "Returns all branches for a repository.", tags = "Repository")
+  @ApiResponse(
+    responseCode = "200",
+    description = "success",
+    content = @Content(
+      mediaType = VndMediaType.BRANCH_COLLECTION,
+      schema = @Schema(implementation = CollectionDto.class)
+    )
+  )
+  @ApiResponse(responseCode = "400", description = "branches not supported for given repository")
+  @ApiResponse(responseCode = "401", description = "not authenticated / invalid credentials")
+  @ApiResponse(responseCode = "403", description = "not authorized, the current user does not have the \"read repository\" privilege")
+  @ApiResponse(
+    responseCode = "404",
+    description = "not found, no repository found for the given namespace and name",
+    content = @Content(
+      mediaType = VndMediaType.ERROR_TYPE,
+      schema = @Schema(implementation = ErrorDto.class)
+    )
+  )
+  @ApiResponse(
+    responseCode = "500",
+    description = "internal server error",
+    content = @Content(
+      mediaType = VndMediaType.ERROR_TYPE,
+      schema = @Schema(implementation = ErrorDto.class)
+    ))
  public Response getAll(@PathParam("namespace") String namespace, @PathParam("name") String name) throws IOException {
    try (RepositoryService repositoryService = serviceFactory.create(new NamespaceAndName(namespace, name))) {
      Branches branches = repositoryService.getBranchesCommand().getBranches();
--- a/scm-webapp/src/main/java/sonia/scm/api/v2/resources/ChangesetRootResource.java
+++ b/scm-webapp/src/main/java/sonia/scm/api/v2/resources/ChangesetRootResource.java
@@ -1,11 +1,9 @@
 package sonia.scm.api.v2.resources;

-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 lombok.extern.slf4j.Slf4j;
 import sonia.scm.PageResult;
 import sonia.scm.repository.Changeset;
@@ -45,58 +43,10 @@ public class ChangesetRootResource {
    this.changesetToChangesetDtoMapper = changesetToChangesetDtoMapper;
  }

-  @GET
-  @Path("{id}")
-  @Produces(VndMediaType.CHANGESET)
-  @Operation(summary = "Collection of changesets", description = "Returns a collection of changesets.", tags = "Repository")
-  @ApiResponse(
-    responseCode = "200",
-    description = "success",
-    content = @Content(
-      mediaType = VndMediaType.CHANGESET,
-      schema = @Schema(implementation = ChangesetDto.class)
-    )
-  )
-  @ApiResponse(responseCode = "401", description = "not authenticated / invalid credentials")
-  @ApiResponse(responseCode = "403", description = "not authorized, the current user has no privileges to read the changeset")
-  @ApiResponse(
-    responseCode = "404",
-    description = "not found, no changeset with the specified id is available in the repository",
-    content = @Content(
-      mediaType = VndMediaType.ERROR_TYPE,
-      schema = @Schema(implementation = ErrorDto.class)
-    ))
-  @ApiResponse(
-    responseCode = "500",
-    description = "internal server error",
-    content = @Content(
-      mediaType = VndMediaType.ERROR_TYPE,
-      schema = @Schema(implementation = ErrorDto.class)
-    ))
-  public Response get(@PathParam("namespace") String namespace, @PathParam("name") String name, @PathParam("id") String id) throws IOException {
-    try (RepositoryService repositoryService = serviceFactory.create(new NamespaceAndName(namespace, name))) {
-      Repository repository = repositoryService.getRepository();
-      RepositoryPermissions.read(repository).check();
-      ChangesetPagingResult changesets = repositoryService.getLogCommand()
-        .setStartChangeset(id)
-        .setEndChangeset(id)
-        .getChangesets();
-      if (changesets != null && changesets.getChangesets() != null && !changesets.getChangesets().isEmpty()) {
-        Optional<Changeset> changeset = changesets.getChangesets().stream().filter(ch -> ch.getId().equals(id)).findFirst();
-        if (!changeset.isPresent()) {
-          return Response.status(Response.Status.NOT_FOUND).build();
-        }
-        return Response.ok(changesetToChangesetDtoMapper.map(changeset.get(), repository)).build();
-      } else {
-        return Response.status(Response.Status.NOT_FOUND).build();
-      }
-    }
-  }
-
  @GET
  @Path("")
  @Produces(VndMediaType.CHANGESET_COLLECTION)
-  @Operation(summary = "Specific changeset", description = "Returns a specific changeset.", tags = "Repository")
+  @Operation(summary = "Collection of changesets", description = "Returns a collection of changesets.", tags = "Repository")
  @ApiResponse(
    responseCode = "200",
    description = "success",
@@ -143,4 +93,52 @@ public class ChangesetRootResource {
      }
    }
  }
+
+  @GET
+  @Path("{id}")
+  @Produces(VndMediaType.CHANGESET)
+  @Operation(summary = "Specific changeset", description = "Returns a specific changeset.", tags = "Repository")
+  @ApiResponse(
+    responseCode = "200",
+    description = "success",
+    content = @Content(
+      mediaType = VndMediaType.CHANGESET,
+      schema = @Schema(implementation = ChangesetDto.class)
+    )
+  )
+  @ApiResponse(responseCode = "401", description = "not authenticated / invalid credentials")
+  @ApiResponse(responseCode = "403", description = "not authorized, the current user has no privileges to read the changeset")
+  @ApiResponse(
+    responseCode = "404",
+    description = "not found, no changeset with the specified id is available in the repository",
+    content = @Content(
+      mediaType = VndMediaType.ERROR_TYPE,
+      schema = @Schema(implementation = ErrorDto.class)
+    ))
+  @ApiResponse(
+    responseCode = "500",
+    description = "internal server error",
+    content = @Content(
+      mediaType = VndMediaType.ERROR_TYPE,
+      schema = @Schema(implementation = ErrorDto.class)
+    ))
+  public Response get(@PathParam("namespace") String namespace, @PathParam("name") String name, @PathParam("id") String id) throws IOException {
+    try (RepositoryService repositoryService = serviceFactory.create(new NamespaceAndName(namespace, name))) {
+      Repository repository = repositoryService.getRepository();
+      RepositoryPermissions.read(repository).check();
+      ChangesetPagingResult changesets = repositoryService.getLogCommand()
+        .setStartChangeset(id)
+        .setEndChangeset(id)
+        .getChangesets();
+      if (changesets != null && changesets.getChangesets() != null && !changesets.getChangesets().isEmpty()) {
+        Optional<Changeset> changeset = changesets.getChangesets().stream().filter(ch -> ch.getId().equals(id)).findFirst();
+        if (!changeset.isPresent()) {
+          return Response.status(Response.Status.NOT_FOUND).build();
+        }
+        return Response.ok(changesetToChangesetDtoMapper.map(changeset.get(), repository)).build();
+      } else {
+        return Response.status(Response.Status.NOT_FOUND).build();
+      }
+    }
+  }
 }
--- 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
@@ -78,7 +78,7 @@ public class GroupResource {
   */
  @DELETE
  @Path("")
-  @Operation(summary = "Delete group", description = "Deletes a group.", tags = "Group")
+  @Operation(summary = "Delete group", description = "Deletes the group with the given id.", 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")
--- a/scm-webapp/src/main/java/sonia/scm/api/v2/resources/IncomingRootResource.java
+++ b/scm-webapp/src/main/java/sonia/scm/api/v2/resources/IncomingRootResource.java
@@ -1,9 +1,10 @@
 package sonia.scm.api.v2.resources;

 import com.google.inject.Inject;
-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.PageResult;
 import sonia.scm.repository.Changeset;
 import sonia.scm.repository.ChangesetPagingResult;
@@ -81,17 +82,34 @@ public class IncomingRootResource {
   * @return
   * @throws Exception
   */
-  @Path("{source}/{target}/changesets")
  @GET
-  @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 changeset"),
-    @ResponseCode(code = 404, condition = "not found, no changesets available in the repository"),
-    @ResponseCode(code = 500, condition = "internal server error")
-  })
+  @Path("{source}/{target}/changesets")
  @Produces(VndMediaType.CHANGESET_COLLECTION)
-  @TypeHint(CollectionDto.class)
+  @Operation(summary = "Incoming changesets", description = "Get the incoming changesets from source to target", tags = "Repository")
+  @ApiResponse(
+    responseCode = "200",
+    description = "success",
+    content = @Content(
+      mediaType = VndMediaType.CHANGESET_COLLECTION,
+      schema = @Schema(implementation = CollectionDto.class)
+    )
+  )
+  @ApiResponse(responseCode = "401", description = "not authenticated / invalid credentials")
+  @ApiResponse(responseCode = "403", description = "not authorized, the current user has no privileges to read the changeset")
+  @ApiResponse(
+    responseCode = "404",
+    description = "not found, no changesets available in the repository",
+    content = @Content(
+      mediaType = VndMediaType.ERROR_TYPE,
+      schema = @Schema(implementation = ErrorDto.class)
+    ))
+  @ApiResponse(
+    responseCode = "500",
+    description = "internal server error",
+    content = @Content(
+      mediaType = VndMediaType.ERROR_TYPE,
+      schema = @Schema(implementation = ErrorDto.class)
+    ))
  public Response incomingChangesets(@PathParam("namespace") String namespace,
                                     @PathParam("name") String name,
                                     @PathParam("source") String source,
@@ -117,18 +135,34 @@ public class IncomingRootResource {
    }
  }

-
-  @Path("{source}/{target}/diff")
  @GET
-  @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 changeset"),
-    @ResponseCode(code = 404, condition = "not found, no changesets available in the repository"),
-    @ResponseCode(code = 500, condition = "internal server error")
-  })
+  @Path("{source}/{target}/diff")
  @Produces(VndMediaType.DIFF)
-  @TypeHint(CollectionDto.class)
+  @Operation(summary = "Incoming diff", description = "Get the incoming diff from source to target", tags = "Repository")
+  @ApiResponse(
+    responseCode = "200",
+    description = "success",
+    content = @Content(
+      mediaType = VndMediaType.DIFF,
+      schema = @Schema(implementation = CollectionDto.class)
+    )
+  )
+  @ApiResponse(responseCode = "401", description = "not authenticated / invalid credentials")
+  @ApiResponse(responseCode = "403", description = "not authorized, the current user has no privileges to read the changeset")
+  @ApiResponse(
+    responseCode = "404",
+    description = "not found, no changesets available in the repository",
+    content = @Content(
+      mediaType = VndMediaType.ERROR_TYPE,
+      schema = @Schema(implementation = ErrorDto.class)
+    ))
+  @ApiResponse(
+    responseCode = "500",
+    description = "internal server error",
+    content = @Content(
+      mediaType = VndMediaType.ERROR_TYPE,
+      schema = @Schema(implementation = ErrorDto.class)
+    ))
  public Response incomingDiff(@PathParam("namespace") String namespace,
                               @PathParam("name") String name,
                               @PathParam("source") String source,
@@ -155,14 +189,32 @@ public class IncomingRootResource {
  @GET
  @Path("{source}/{target}/diff/parsed")
  @Produces(VndMediaType.DIFF_PARSED)
-  @StatusCodes({
-    @ResponseCode(code = 200, condition = "success"),
-    @ResponseCode(code = 400, condition = "Bad Request"),
-    @ResponseCode(code = 401, condition = "not authenticated / invalid credentials"),
-    @ResponseCode(code = 403, condition = "not authorized, the current user has no privileges to read the diff"),
-    @ResponseCode(code = 404, condition = "not found, source or target branch for the repository not available or repository not found"),
-    @ResponseCode(code = 500, condition = "internal server error")
-  })
+  @Operation(summary = "Incoming parsed diff", description = "Get the incoming parsed diff from source to target", tags = "Repository")
+  @ApiResponse(
+    responseCode = "200",
+    description = "success",
+    content = @Content(
+      mediaType = VndMediaType.DIFF_PARSED,
+      schema = @Schema(implementation = CollectionDto.class)
+    )
+  )
+  @ApiResponse(responseCode = "400", description = "bad request")
+  @ApiResponse(responseCode = "401", description = "not authenticated / invalid credentials")
+  @ApiResponse(responseCode = "403", description = "not authorized, the current user has no privileges to read the diff")
+  @ApiResponse(
+    responseCode = "404",
+    description = "not found, source or target branch for the repository not available or repository not found",
+    content = @Content(
+      mediaType = VndMediaType.ERROR_TYPE,
+      schema = @Schema(implementation = ErrorDto.class)
+    ))
+  @ApiResponse(
+    responseCode = "500",
+    description = "internal server error",
+    content = @Content(
+      mediaType = VndMediaType.ERROR_TYPE,
+      schema = @Schema(implementation = ErrorDto.class)
+    ))
  public Response incomingDiffParsed(@PathParam("namespace") String namespace,
                            @PathParam("name") String name,
                            @PathParam("source") String source,
--- a/scm-webapp/src/main/java/sonia/scm/api/v2/resources/ModificationsRootResource.java
+++ b/scm-webapp/src/main/java/sonia/scm/api/v2/resources/ModificationsRootResource.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.repository.Modifications;
 import sonia.scm.repository.NamespaceAndName;
 import sonia.scm.repository.api.RepositoryService;
@@ -33,16 +34,27 @@ public class ModificationsRootResource {
   * file modifications are for example: Modified, Added or Removed.
   */
  @GET
-  @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 modifications"),
-    @ResponseCode(code = 404, condition = "not found, no changeset with the specified id is available in the repository"),
-    @ResponseCode(code = 500, condition = "internal server error")
-  })
-  @Produces(VndMediaType.MODIFICATIONS)
-  @TypeHint(ModificationsDto.class)
  @Path("{revision}")
+  @Produces(VndMediaType.MODIFICATIONS)
+  @Operation(summary = "File modifications", description = "Get the file modifications related to a revision.", tags = "Repository")
+  @ApiResponse(
+    responseCode = "200",
+    description = "success",
+    content = @Content(
+      mediaType = VndMediaType.MODIFICATIONS,
+      schema = @Schema(implementation = ModificationsDto.class)
+    )
+  )
+  @ApiResponse(responseCode = "401", description = "not authenticated / invalid credentials")
+  @ApiResponse(responseCode = "403", description = "not authorized, the current user has no privileges to read the modifications")
+  @ApiResponse(
+    responseCode = "404",
+    description = "not found, no changeset with the specified id is available in the repository",
+    content = @Content(
+      mediaType = VndMediaType.ERROR_TYPE,
+      schema = @Schema(implementation = ErrorDto.class)
+    ))
+  @ApiResponse(responseCode = "500", description = "internal server error")
  public Response get(@PathParam("namespace") String namespace, @PathParam("name") String name, @PathParam("revision") String revision) throws IOException {
    try (RepositoryService repositoryService = serviceFactory.create(new NamespaceAndName(namespace, name))) {
      Modifications modifications = repositoryService.getModificationsCommand()
--- a/scm-webapp/src/main/java/sonia/scm/api/v2/resources/NamespaceStrategyResource.java
+++ b/scm-webapp/src/main/java/sonia/scm/api/v2/resources/NamespaceStrategyResource.java
@@ -1,6 +1,7 @@
 package sonia.scm.api.v2.resources;

 import de.otto.edison.hal.Links;
+import io.swagger.v3.oas.annotations.Operation;
 import sonia.scm.repository.NamespaceStrategy;
 import sonia.scm.web.VndMediaType;

@@ -42,6 +43,7 @@ public class NamespaceStrategyResource {
  @GET
  @Path("")
  @Produces(VndMediaType.NAMESPACE_STRATEGIES)
+  @Operation(summary = "List of namespace strategies", description = "Returns all available namespace strategies and the current selected.", tags = "Repository")
  public NamespaceStrategiesDto get(@Context UriInfo uriInfo) {
    String currentStrategy = strategyAsString(namespaceStrategyProvider.get());
    List<String> availableStrategies = collectStrategyNames();
--- a/scm-webapp/src/main/java/sonia/scm/api/v2/resources/RepositoryCollectionResource.java
+++ b/scm-webapp/src/main/java/sonia/scm/api/v2/resources/RepositoryCollectionResource.java
@@ -1,10 +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.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 org.apache.shiro.SecurityUtils;
 import sonia.scm.repository.Repository;
 import sonia.scm.repository.RepositoryInitializer;
@@ -63,13 +64,26 @@ public class RepositoryCollectionResource {
  @GET
  @Path("")
  @Produces(VndMediaType.REPOSITORY_COLLECTION)
-  @TypeHint(CollectionDto.class)
-  @StatusCodes({
-    @ResponseCode(code = 200, condition = "success"),
-    @ResponseCode(code = 401, condition = "not authenticated / invalid credentials"),
-    @ResponseCode(code = 403, condition = "not authorized, the current user does not have the \"repository\" privilege"),
-    @ResponseCode(code = 500, condition = "internal server error")
-  })
+  @Operation(summary = "List of repositories", description = "Returns all repositories for a given page number with a given page size.", tags = "Repository")
+
+
+  @ApiResponse(
+    responseCode = "200",
+    description = "success",
+    content = @Content(
+      mediaType = VndMediaType.REPOSITORY_COLLECTION,
+      schema = @Schema(implementation = CollectionDto.class)
+    )
+  )
+  @ApiResponse(responseCode = "401", description = "not authenticated / invalid credentials")
+  @ApiResponse(responseCode = "403", description = "not authorized, the current user does not have the \"repository\" privilege")
+  @ApiResponse(
+    responseCode = "500",
+    description = "internal server error",
+    content = @Content(
+      mediaType = VndMediaType.ERROR_TYPE,
+      schema = @Schema(implementation = ErrorDto.class)
+    ))
  public Response getAll(@DefaultValue("0") @QueryParam("page") int page,
                         @DefaultValue("" + DEFAULT_PAGE_SIZE) @QueryParam("pageSize") int pageSize,
                         @QueryParam("sortBy") String sortBy,
@@ -92,14 +106,18 @@ public class RepositoryCollectionResource {
  @POST
  @Path("")
  @Consumes(VndMediaType.REPOSITORY)
-  @StatusCodes({
-    @ResponseCode(code = 201, condition = "create success"),
-    @ResponseCode(code = 401, condition = "not authenticated / invalid credentials"),
-    @ResponseCode(code = 403, condition = "not authorized, the current user does not have the \"repository\" privilege"),
-    @ResponseCode(code = 409, condition = "conflict, a repository with this name already exists"),
-    @ResponseCode(code = 500, condition = "internal server error")
-  })
-  @TypeHint(TypeHint.NO_CONTENT.class)
+  @Operation(summary = "Create repository", description = "Creates a new repository.", tags = "Repository")
+  @ApiResponse(responseCode = "201", description = "create success")
+  @ApiResponse(responseCode = "401", description = "not authenticated / invalid credentials")
+  @ApiResponse(responseCode = "403", description = "not authorized, the current user does not have the \"repository\" privilege")
+  @ApiResponse(responseCode = "409", description = "conflict, a repository with this name already exists")
+  @ApiResponse(
+    responseCode = "500",
+    description = "internal server error",
+    content = @Content(
+      mediaType = VndMediaType.ERROR_TYPE,
+      schema = @Schema(implementation = ErrorDto.class)
+    ))
  @ResponseHeaders(@ResponseHeader(name = "Location", description = "uri to the created repository"))
  public Response create(@Valid RepositoryDto repository, @QueryParam("initialize") boolean initialize) {
    AtomicReference<Repository> reference = new AtomicReference<>();
--- a/scm-webapp/src/main/java/sonia/scm/api/v2/resources/RepositoryPermissionRootResource.java
+++ b/scm-webapp/src/main/java/sonia/scm/api/v2/resources/RepositoryPermissionRootResource.java
@@ -1,9 +1,10 @@
 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.StatusCodes;
-import com.webcohesion.enunciate.metadata.rs.TypeHint;
+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.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
 import lombok.extern.slf4j.Slf4j;
 import sonia.scm.AlreadyExistsException;
 import sonia.scm.NotFoundException;
@@ -64,17 +65,30 @@ public class RepositoryPermissionRootResource {
   * @return a web response with the status code 201 and the url to GET the added permission
   */
  @POST
-  @StatusCodes({
-    @ResponseCode(code = 201, condition = "creates", additionalHeaders = {
-      @ResponseHeader(name = "Location", description = "uri of the  created permission")
-    }),
-    @ResponseCode(code = 500, condition = "internal server error"),
-    @ResponseCode(code = 404, condition = "not found"),
-    @ResponseCode(code = 409, condition = "conflict")
-  })
-  @TypeHint(TypeHint.NO_CONTENT.class)
-  @Consumes(VndMediaType.REPOSITORY_PERMISSION)
  @Path("")
+  @Consumes(VndMediaType.REPOSITORY_PERMISSION)
+  @Operation(summary = "Create repository-specific permission", description = "Adds a new permission to the user or group managed by the repository.", tags = {"Repository", "Permissions"})
+  @ApiResponse(
+    responseCode = "201",
+    description = "creates",
+    headers = @Header(name = "Location", description = "uri of the created permission")
+  )
+  @ApiResponse(
+    responseCode = "404",
+    description = "not found",
+    content = @Content(
+      mediaType = VndMediaType.ERROR_TYPE,
+      schema = @Schema(implementation = ErrorDto.class)
+    ))
+  @ApiResponse(responseCode = "409", description = "conflict")
+  @ApiResponse(
+    responseCode = "500",
+    description = "internal server error",
+    content = @Content(
+      mediaType = VndMediaType.ERROR_TYPE,
+      schema = @Schema(implementation = ErrorDto.class)
+    )
+  )
  public Response create(@PathParam("namespace") String namespace, @PathParam("name") String name, @Valid RepositoryPermissionDto permission) {
    log.info("try to add new permission: {}", permission);
    Repository repository = load(namespace, name);
@@ -95,14 +109,32 @@ public class RepositoryPermissionRootResource {
   * @throws NotFoundException if the repository does not exists
   */
  @GET
-  @StatusCodes({
-    @ResponseCode(code = 200, condition = "ok"),
-    @ResponseCode(code = 404, condition = "not found"),
-    @ResponseCode(code = 500, condition = "internal server error")
-  })
-  @Produces(VndMediaType.REPOSITORY_PERMISSION)
-  @TypeHint(RepositoryPermissionDto.class)
  @Path("{permission-name}")
+  @Produces(VndMediaType.REPOSITORY_PERMISSION)
+  @Operation(summary = "Get single repository-specific permission", description = "Get the searched permission with permission name related to a repository.", tags = {"Repository", "Permissions"})
+  @ApiResponse(
+    responseCode = "200",
+    description = "success",
+    content = @Content(
+      mediaType = VndMediaType.REPOSITORY_PERMISSION,
+      schema = @Schema(implementation = RepositoryPermissionDto.class)
+    )
+  )
+  @ApiResponse(
+    responseCode = "404",
+    description = "not found",
+    content = @Content(
+      mediaType = VndMediaType.ERROR_TYPE,
+      schema = @Schema(implementation = ErrorDto.class)
+    ))
+  @ApiResponse(
+    responseCode = "500",
+    description = "internal server error",
+    content = @Content(
+      mediaType = VndMediaType.ERROR_TYPE,
+      schema = @Schema(implementation = ErrorDto.class)
+    )
+  )
  public Response get(@PathParam("namespace") String namespace, @PathParam("name") String name, @PathParam("permission-name") String permissionName) {
    Repository repository = load(namespace, name);
    RepositoryPermissions.permissionRead(repository).check();
@@ -125,14 +157,32 @@ public class RepositoryPermissionRootResource {
   * @throws NotFoundException if the repository does not exists
   */
  @GET
-  @StatusCodes({
-    @ResponseCode(code = 200, condition = "ok"),
-    @ResponseCode(code = 404, condition = "not found"),
-    @ResponseCode(code = 500, condition = "internal server error")
-  })
-  @Produces(VndMediaType.REPOSITORY_PERMISSION)
-  @TypeHint(RepositoryPermissionDto.class)
  @Path("")
+  @Produces(VndMediaType.REPOSITORY_PERMISSION)
+  @Operation(summary = "List of repository-specific permissions", description = "Get all permissions related to a repository.", tags = {"Repository", "Permissions"})
+  @ApiResponse(
+    responseCode = "200",
+    description = "success",
+    content = @Content(
+      mediaType = VndMediaType.REPOSITORY_PERMISSION,
+      schema = @Schema(implementation = RepositoryPermissionDto.class)
+    )
+  )
+  @ApiResponse(
+    responseCode = "404",
+    description = "not found",
+    content = @Content(
+      mediaType = VndMediaType.ERROR_TYPE,
+      schema = @Schema(implementation = ErrorDto.class)
+    ))
+  @ApiResponse(
+    responseCode = "500",
+    description = "internal server error",
+    content = @Content(
+      mediaType = VndMediaType.ERROR_TYPE,
+      schema = @Schema(implementation = ErrorDto.class)
+    )
+  )
  public Response getAll(@PathParam("namespace") String namespace, @PathParam("name") String name) {
    Repository repository = load(namespace, name);
    RepositoryPermissions.permissionRead(repository).check();
@@ -148,14 +198,19 @@ public class RepositoryPermissionRootResource {
   * @return a web response with the status code 204
   */
  @PUT
-  @StatusCodes({
-    @ResponseCode(code = 204, condition = "update success"),
-    @ResponseCode(code = 401, condition = "not authenticated / invalid credentials"),
-    @ResponseCode(code = 500, condition = "internal server error")
-  })
-  @TypeHint(TypeHint.NO_CONTENT.class)
-  @Consumes(VndMediaType.REPOSITORY_PERMISSION)
  @Path("{permission-name}")
+  @Consumes(VndMediaType.REPOSITORY_PERMISSION)
+  @Operation(summary = "Update repository-specific permission", description = "Update a permission to the user or group managed by the repository.", tags = {"Repository", "Permissions"})
+  @ApiResponse(responseCode = "204", description = "update success")
+  @ApiResponse(responseCode = "401", description = "not authenticated / invalid credentials")
+  @ApiResponse(
+    responseCode = "500",
+    description = "internal server error",
+    content = @Content(
+      mediaType = VndMediaType.ERROR_TYPE,
+      schema = @Schema(implementation = ErrorDto.class)
+    )
+  )
  public Response update(@PathParam("namespace") String namespace,
                         @PathParam("name") String name,
                         @PathParam("permission-name") String permissionName,
@@ -194,14 +249,19 @@ public class RepositoryPermissionRootResource {
   * @return a web response with the status code 204
   */
  @DELETE
-  @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"),
-    @ResponseCode(code = 500, condition = "internal server error")
-  })
-  @TypeHint(TypeHint.NO_CONTENT.class)
  @Path("{permission-name}")
+  @Operation(summary = "Delete repository-specific permission", description = "Delete a permission with the given name.", tags = {"Repository", "Permissions"})
+  @ApiResponse(responseCode = "204", description = "delete success or nothing to delete")
+  @ApiResponse(responseCode = "401", description = "not authenticated / invalid credentials")
+  @ApiResponse(responseCode = "403", description = "not authorized")
+  @ApiResponse(
+    responseCode = "500",
+    description = "internal server error",
+    content = @Content(
+      mediaType = VndMediaType.ERROR_TYPE,
+      schema = @Schema(implementation = ErrorDto.class)
+    )
+  )
  public Response delete(@PathParam("namespace") String namespace,
                         @PathParam("name") String name,
                         @PathParam("permission-name") String permissionName) {
--- a/scm-webapp/src/main/java/sonia/scm/api/v2/resources/RepositoryResource.java
+++ b/scm-webapp/src/main/java/sonia/scm/api/v2/resources/RepositoryResource.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;
@@ -91,7 +88,7 @@ public class RepositoryResource {
  @GET
  @Path("")
  @Produces(VndMediaType.REPOSITORY)
-  @Operation(summary = "Returns a single repository", description = "Returns the repository for the given namespace and name.", tags = "Repository")
+  @Operation(summary = "Get single repository", description = "Returns the repository for the given namespace and name.", tags = "Repository")
  @ApiResponse(
    responseCode = "200",
    description = "success",
@@ -139,13 +136,11 @@ public class RepositoryResource {
   */
  @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 \"repository\" privilege"),
-    @ResponseCode(code = 500, condition = "internal server error")
-  })
-  @TypeHint(TypeHint.NO_CONTENT.class)
+  @Operation(summary = "Delete repository", description = "Deletes the repository with the given namespace and name.", tags = "Repository")
+  @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 does not have the \"repository\" privilege")
+  @ApiResponse(responseCode = "500", description = "internal server error")
  public Response delete(@PathParam("namespace") String namespace, @PathParam("name") String name) {
    return adapter.delete(loadBy(namespace, name));
  }
@@ -162,15 +157,19 @@ public class RepositoryResource {
  @PUT
  @Path("")
  @Consumes(VndMediaType.REPOSITORY)
-  @StatusCodes({
-    @ResponseCode(code = 204, condition = "update success"),
-    @ResponseCode(code = 400, condition = "invalid body, e.g. illegal change of namespace or name"),
-    @ResponseCode(code = 401, condition = "not authenticated / invalid credentials"),
-    @ResponseCode(code = 403, condition = "not authorized, the current user does not have the \"repository\" privilege"),
-    @ResponseCode(code = 404, condition = "not found, no repository with the specified namespace and name available"),
-    @ResponseCode(code = 500, condition = "internal server error")
-  })
-  @TypeHint(TypeHint.NO_CONTENT.class)
+  @Operation(summary = "Update repository", description = "Modifies the repository for the given namespace and name.", tags = "Repository")
+  @ApiResponse(responseCode = "204", description = "update success")
+  @ApiResponse(responseCode = "400", description = "invalid body, e.g. illegal change of namespace or name")
+  @ApiResponse(responseCode = "401", description = "not authenticated / invalid credentials")
+  @ApiResponse(responseCode = "403", description = "not authorized, the current user does not have the \"repository\" privilege")
+  @ApiResponse(
+    responseCode = "404",
+    description = "not found, no repository with the specified namespace and name available",
+    content = @Content(
+      mediaType = VndMediaType.ERROR_TYPE,
+      schema = @Schema(implementation = ErrorDto.class)
+    ))
+  @ApiResponse(responseCode = "500", description = "internal server error")
  public Response update(@PathParam("namespace") String namespace, @PathParam("name") String name, @Valid RepositoryDto repository) {
    return adapter.update(
      loadBy(namespace, name),
--- a/scm-webapp/src/main/java/sonia/scm/api/v2/resources/RepositoryRoleCollectionResource.java
+++ b/scm-webapp/src/main/java/sonia/scm/api/v2/resources/RepositoryRoleCollectionResource.java
@@ -1,10 +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.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.repository.RepositoryRole;
 import sonia.scm.repository.RepositoryRoleManager;
 import sonia.scm.web.VndMediaType;
@@ -51,14 +52,25 @@ public class RepositoryRoleCollectionResource {
  @GET
  @Path("")
  @Produces(VndMediaType.REPOSITORY_ROLE_COLLECTION)
-  @TypeHint(CollectionDto.class)
-  @StatusCodes({
-    @ResponseCode(code = 200, condition = "success"),
-    @ResponseCode(code = 400, condition = "\"sortBy\" field unknown"),
-    @ResponseCode(code = 401, condition = "not authenticated / invalid credentials"),
-    @ResponseCode(code = 403, condition = "not authorized, the current repositoryRole does not have the \"repositoryRole\" privilege"),
-    @ResponseCode(code = 500, condition = "internal server error")
-  })
+  @Operation(summary = "List of repository roles", description = "Returns all repository roles for a given page number with a given page size.", tags = "Repository role")
+  @ApiResponse(
+    responseCode = "200",
+    description = "success",
+    content = @Content(
+      mediaType = VndMediaType.REPOSITORY_ROLE_COLLECTION,
+      schema = @Schema(implementation = CollectionDto.class)
+    )
+  )
+  @ApiResponse(responseCode = "400", description = "\"sortBy\" field unknown")
+  @ApiResponse(responseCode = "401", description = "not authenticated / invalid credentials")
+  @ApiResponse(responseCode = "403", description = "not authorized, the current repositoryRole does not have the \"repositoryRole\" privilege")
+  @ApiResponse(
+    responseCode = "500",
+    description = "internal server error",
+    content = @Content(
+      mediaType = VndMediaType.ERROR_TYPE,
+      schema = @Schema(implementation = ErrorDto.class)
+    ))
  public Response getAll(@DefaultValue("0") @QueryParam("page") int page,
    @DefaultValue("" + DEFAULT_PAGE_SIZE) @QueryParam("pageSize") int pageSize,
    @QueryParam("sortBy") String sortBy,
@@ -79,14 +91,18 @@ public class RepositoryRoleCollectionResource {
  @POST
  @Path("")
  @Consumes(VndMediaType.REPOSITORY_ROLE)
-  @StatusCodes({
-    @ResponseCode(code = 201, condition = "create success"),
-    @ResponseCode(code = 401, condition = "not authenticated / invalid credentials"),
-    @ResponseCode(code = 403, condition = "not authorized, the current user does not have the \"repositoryRole\" privilege"),
-    @ResponseCode(code = 409, condition = "conflict, a repository role with this name already exists"),
-    @ResponseCode(code = 500, condition = "internal server error")
-  })
-  @TypeHint(TypeHint.NO_CONTENT.class)
+  @Operation(summary = "Create repository role", description = "Creates a new repository role.", tags = "Repository role")
+  @ApiResponse(responseCode = "201", description = "create success")
+  @ApiResponse(responseCode = "401", description = "not authenticated / invalid credentials")
+  @ApiResponse(responseCode = "403", description = "not authorized, the current user does not have the \"repositoryRole\" privilege")
+  @ApiResponse(responseCode = "409", description = "conflict, a repository role with this name already exists")
+  @ApiResponse(
+    responseCode = "500",
+    description = "internal server error",
+    content = @Content(
+      mediaType = VndMediaType.ERROR_TYPE,
+      schema = @Schema(implementation = ErrorDto.class)
+    ))
  @ResponseHeaders(@ResponseHeader(name = "Location", description = "uri to the created repositoryRole"))
  public Response create(@Valid RepositoryRoleDto repositoryRole) {
    return adapter.create(repositoryRole, () -> dtoToRepositoryRoleMapper.map(repositoryRole), u -> resourceLinks.repositoryRole().self(u.getName()));
--- a/scm-webapp/src/main/java/sonia/scm/api/v2/resources/RepositoryRoleResource.java
+++ b/scm-webapp/src/main/java/sonia/scm/api/v2/resources/RepositoryRoleResource.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.repository.RepositoryRole;
 import sonia.scm.repository.RepositoryRoleManager;
 import sonia.scm.web.VndMediaType;
@@ -45,14 +46,31 @@ public class RepositoryRoleResource {
  @GET
  @Path("")
  @Produces(VndMediaType.REPOSITORY_ROLE)
-  @TypeHint(RepositoryRoleDto.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 repository role"),
-    @ResponseCode(code = 404, condition = "not found, no repository role with the specified name available"),
-    @ResponseCode(code = 500, condition = "internal server error")
-  })
+  @Operation(summary = "Get single repository role", description = "Returns the repository role for the given name.", tags = "Repository role")
+  @ApiResponse(
+    responseCode = "200",
+    description = "success",
+    content = @Content(
+      mediaType = VndMediaType.REPOSITORY_ROLE,
+      schema = @Schema(implementation = RepositoryRoleDto.class)
+    )
+  )
+  @ApiResponse(responseCode = "401", description = "not authenticated / invalid credentials")
+  @ApiResponse(responseCode = "403", description = "not authorized, the current user has no privileges to read the repository role")
+  @ApiResponse(
+    responseCode = "404",
+    description = "not found, no repository role with the specified name available",
+    content = @Content(
+      mediaType = VndMediaType.ERROR_TYPE,
+      schema = @Schema(implementation = ErrorDto.class)
+    ))
+  @ApiResponse(
+    responseCode = "500",
+    description = "internal server error",
+    content = @Content(
+      mediaType = VndMediaType.ERROR_TYPE,
+      schema = @Schema(implementation = ErrorDto.class)
+    ))
  public Response get(@PathParam("name") String name) {
    return adapter.get(name, repositoryRoleToDtoMapper::map);
  }
@@ -66,13 +84,11 @@ public class RepositoryRoleResource {
   */
  @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 \"repositoryRole\" privilege"),
-    @ResponseCode(code = 500, condition = "internal server error")
-  })
-  @TypeHint(TypeHint.NO_CONTENT.class)
+  @Operation(summary = "Delete repository role", description = "Deletes the repository role with the given name.", tags = "Repository role")
+  @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 does not have the \"repositoryRole\" privilege")
+  @ApiResponse(responseCode = "500", description = "internal server error")
  public Response delete(@PathParam("name") String name) {
    return adapter.delete(name);
  }
@@ -88,15 +104,19 @@ public class RepositoryRoleResource {
  @PUT
  @Path("")
  @Consumes(VndMediaType.REPOSITORY_ROLE)
-  @StatusCodes({
-    @ResponseCode(code = 204, condition = "update success"),
-    @ResponseCode(code = 400, condition = "invalid body, e.g. illegal change of repository role name"),
-    @ResponseCode(code = 401, condition = "not authenticated / invalid credentials"),
-    @ResponseCode(code = 403, condition = "not authorized, the current user does not have the \"repositoryRole\" privilege"),
-    @ResponseCode(code = 404, condition = "not found, no repository role with the specified name available"),
-    @ResponseCode(code = 500, condition = "internal server error")
-  })
-  @TypeHint(TypeHint.NO_CONTENT.class)
+  @Operation(summary = "Update repository role", description = "Modifies the repository role for the given name.", tags = "Repository role")
+  @ApiResponse(responseCode = "204", description = "update success")
+  @ApiResponse(responseCode = "400", description = "invalid body, e.g. illegal change of repository role name")
+  @ApiResponse(responseCode = "401", description = "not authenticated / invalid credentials")
+  @ApiResponse(responseCode = "403", description = "not authorized, the current user does not have the \"repositoryRole\" privilege")
+  @ApiResponse(
+    responseCode = "404",
+    description = "not found, no repository role with the specified name available",
+    content = @Content(
+      mediaType = VndMediaType.ERROR_TYPE,
+      schema = @Schema(implementation = ErrorDto.class)
+    ))
+  @ApiResponse(responseCode = "500", description = "internal server error")
  public Response update(@PathParam("name") String name, @Valid RepositoryRoleDto repositoryRole) {
    return adapter.update(name, existing -> dtoToRepositoryRoleMapper.map(repositoryRole));
  }
--- a/scm-webapp/src/main/java/sonia/scm/api/v2/resources/RepositoryRoleRootResource.java
+++ b/scm-webapp/src/main/java/sonia/scm/api/v2/resources/RepositoryRoleRootResource.java
@@ -1,5 +1,8 @@
 package sonia.scm.api.v2.resources;

+import io.swagger.v3.oas.annotations.OpenAPIDefinition;
+import io.swagger.v3.oas.annotations.tags.Tag;
+
 import javax.inject.Inject;
 import javax.inject.Provider;
 import javax.ws.rs.Path;
@@ -7,6 +10,9 @@ import javax.ws.rs.Path;
 /**
 *  RESTful web service resource to manage repository roles.
 */
+@OpenAPIDefinition(tags = {
+  @Tag(name = "Repository role", description = "Repository role related endpoints")
+})
@Path(RepositoryRoleRootResource.REPOSITORY_ROLES_PATH_V2)
 public class RepositoryRoleRootResource {

--- a/scm-webapp/src/main/java/sonia/scm/api/v2/resources/RepositoryTypeCollectionResource.java
+++ b/scm-webapp/src/main/java/sonia/scm/api/v2/resources/RepositoryTypeCollectionResource.java
@@ -1,8 +1,10 @@
 package sonia.scm.api.v2.resources;

-import com.webcohesion.enunciate.metadata.rs.ResponseCode;
-import com.webcohesion.enunciate.metadata.rs.StatusCodes;
 import de.otto.edison.hal.HalRepresentation;
+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.repository.RepositoryManager;
 import sonia.scm.web.VndMediaType;

@@ -24,11 +26,25 @@ public class RepositoryTypeCollectionResource {

  @GET
  @Path("")
-  @StatusCodes({
-    @ResponseCode(code = 200, condition = "success"),
-    @ResponseCode(code = 500, condition = "internal server error")
-  })
  @Produces(VndMediaType.REPOSITORY_TYPE_COLLECTION)
+  @Operation(summary = "List of repository types", description = "Returns all repository types.", tags = "Repository")
+  @ApiResponse(
+    responseCode = "200",
+    description = "success",
+    content = @Content(
+      mediaType = VndMediaType.REPOSITORY_TYPE_COLLECTION,
+      schema = @Schema(implementation = HalRepresentation.class)
+    )
+  )
+  @ApiResponse(responseCode = "400", description = "\"sortBy\" field unknown")
+  @ApiResponse(
+    responseCode = "500",
+    description = "internal server error",
+    content = @Content(
+      mediaType = VndMediaType.ERROR_TYPE,
+      schema = @Schema(implementation = ErrorDto.class)
+    )
+  )
  public HalRepresentation getAll() {
    return mapper.map(repositoryManager.getConfiguredTypes());
  }
--- a/scm-webapp/src/main/java/sonia/scm/api/v2/resources/RepositoryTypeResource.java
+++ b/scm-webapp/src/main/java/sonia/scm/api/v2/resources/RepositoryTypeResource.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.repository.RepositoryManager;
 import sonia.scm.repository.RepositoryType;
 import sonia.scm.web.VndMediaType;
@@ -35,12 +36,24 @@ public class RepositoryTypeResource {
  @GET
  @Path("")
  @Produces(VndMediaType.REPOSITORY_TYPE)
-  @TypeHint(RepositoryTypeDto.class)
-  @StatusCodes({
-    @ResponseCode(code = 200, condition = "success"),
-    @ResponseCode(code = 404, condition = "not found, no repository type with the specified name available"),
-    @ResponseCode(code = 500, condition = "internal server error")
-  })
+  @Operation(summary = "Get single repository type", description = "Returns the specified repository type for the given name.", tags = "Repository")
+  @ApiResponse(
+    responseCode = "200",
+    description = "success",
+    content = @Content(
+      mediaType = VndMediaType.REPOSITORY_TYPE,
+      schema = @Schema(implementation = RepositoryTypeDto.class)
+    )
+  )
+  @ApiResponse(responseCode = "404", description = "not found, no repository type with the specified name available")
+  @ApiResponse(
+    responseCode = "500",
+    description = "internal server error",
+    content = @Content(
+      mediaType = VndMediaType.ERROR_TYPE,
+      schema = @Schema(implementation = ErrorDto.class)
+    )
+  )
  public Response get(@PathParam("name") String name) {
    for (RepositoryType type : repositoryManager.getConfiguredTypes()) {
      if (name.equalsIgnoreCase(type.getName())) {
--- a/scm-webapp/src/main/java/sonia/scm/api/v2/resources/RepositoryVerbResource.java
+++ b/scm-webapp/src/main/java/sonia/scm/api/v2/resources/RepositoryVerbResource.java
@@ -1,8 +1,10 @@
 package sonia.scm.api.v2.resources;

-import com.webcohesion.enunciate.metadata.rs.ResponseCode;
-import com.webcohesion.enunciate.metadata.rs.StatusCodes;
 import de.otto.edison.hal.Links;
+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.security.RepositoryPermissionProvider;
 import sonia.scm.web.VndMediaType;

@@ -30,11 +32,23 @@ public class RepositoryVerbResource {

  @GET
  @Path("")
-  @StatusCodes({
-    @ResponseCode(code = 200, condition = "success"),
-    @ResponseCode(code = 500, condition = "internal server error")
-  })
  @Produces(VndMediaType.REPOSITORY_VERB_COLLECTION)
+  @Operation(summary = "List of repository verbs", description = "Returns all repository-specific permissions.", hidden = true)
+  @ApiResponse(
+    responseCode = "200",
+    description = "success",
+    content = @Content(
+      mediaType = VndMediaType.REPOSITORY_VERB_COLLECTION,
+      schema = @Schema(implementation = RepositoryVerbsDto.class)
+    )
+  )
+  @ApiResponse(
+    responseCode = "500",
+    description = "internal server error",
+    content = @Content(
+      mediaType = VndMediaType.ERROR_TYPE,
+      schema = @Schema(implementation = ErrorDto.class)
+    ))
  public RepositoryVerbsDto getAll() {
    return new RepositoryVerbsDto(
      Links.linkingTo().self(resourceLinks.repositoryVerbs().self()).build(),
--- a/scm-webapp/src/main/java/sonia/scm/api/v2/resources/SourceRootResource.java
+++ b/scm-webapp/src/main/java/sonia/scm/api/v2/resources/SourceRootResource.java
@@ -1,5 +1,6 @@
 package sonia.scm.api.v2.resources;

+import io.swagger.v3.oas.annotations.Operation;
 import sonia.scm.repository.BrowserResult;
 import sonia.scm.repository.NamespaceAndName;
 import sonia.scm.repository.api.BrowseCommandBuilder;
@@ -32,22 +33,25 @@ public class SourceRootResource {
  }

  @GET
-  @Produces(VndMediaType.SOURCE)
  @Path("")
+  @Produces(VndMediaType.SOURCE)
+  @Operation(summary = "List of sources", description = "Returns all sources for repository head.", tags = "Repository")
  public Response getAllWithoutRevision(@PathParam("namespace") String namespace, @PathParam("name") String name) throws IOException {
    return getSource(namespace, name, "/", null);
  }

  @GET
-  @Produces(VndMediaType.SOURCE)
  @Path("{revision}")
+  @Produces(VndMediaType.SOURCE)
+  @Operation(summary = "List of sources by revision", description = "Returns all sources for the given revision.", tags = "Repository")
  public Response getAll(@PathParam("namespace") String namespace, @PathParam("name") String name, @PathParam("revision") String revision) throws IOException {
    return getSource(namespace, name, "/", revision);
  }

  @GET
-  @Produces(VndMediaType.SOURCE)
  @Path("{revision}/{path: .*}")
+  @Produces(VndMediaType.SOURCE)
+  @Operation(summary = "List of sources by revision in path", description = "Returns all sources for the given revision in a specific path.", tags = "Repository")
  public Response get(@PathParam("namespace") String namespace, @PathParam("name") String name, @PathParam("revision") String revision, @PathParam("path") String path) throws IOException {
    return getSource(namespace, name, path, revision);
  }
--- a/scm-webapp/src/main/java/sonia/scm/api/v2/resources/TagRootResource.java
+++ b/scm-webapp/src/main/java/sonia/scm/api/v2/resources/TagRootResource.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.NotFoundException;
 import sonia.scm.repository.NamespaceAndName;
 import sonia.scm.repository.Repository;
@@ -39,17 +40,27 @@ public class TagRootResource {
    this.tagToTagDtoMapper = tagToTagDtoMapper;
  }

-
  @GET
  @Path("")
-  @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 tags"),
-    @ResponseCode(code = 500, condition = "internal server error")
-  })
  @Produces(VndMediaType.TAG_COLLECTION)
-  @TypeHint(CollectionDto.class)
+  @Operation(summary = "List of tags", description = "Returns the tags for the given namespace and name.", tags = "Repository")
+  @ApiResponse(
+    responseCode = "200",
+    description = "success",
+    content = @Content(
+      mediaType = VndMediaType.TAG_COLLECTION,
+      schema = @Schema(implementation = CollectionDto.class)
+    )
+  )
+  @ApiResponse(responseCode = "401", description = "not authenticated / invalid credentials")
+  @ApiResponse(responseCode = "403", description = "not authorized, the current user has no privileges to read the tags")
+  @ApiResponse(
+    responseCode = "500",
+    description = "internal server error",
+    content = @Content(
+      mediaType = VndMediaType.ERROR_TYPE,
+      schema = @Schema(implementation = ErrorDto.class)
+    ))
  public Response getAll(@PathParam("namespace") String namespace, @PathParam("name") String name) throws IOException {
    try (RepositoryService repositoryService = serviceFactory.create(new NamespaceAndName(namespace, name))) {
      Tags tags = getTags(repositoryService);
@@ -65,16 +76,33 @@ public class TagRootResource {


  @GET
-  @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 tags"),
-    @ResponseCode(code = 404, condition = "not found, no tag available in the repository"),
-    @ResponseCode(code = 500, condition = "internal server error")
-  })
-  @Produces(VndMediaType.TAG)
-  @TypeHint(TagDto.class)
  @Path("{tagName}")
+  @Produces(VndMediaType.TAG)
+  @Operation(summary = "Get tag", description = "Returns the tag for the given name.", tags = "Repository")
+  @ApiResponse(
+    responseCode = "200",
+    description = "success",
+    content = @Content(
+      mediaType = VndMediaType.TAG,
+      schema = @Schema(implementation = TagDto.class)
+    )
+  )
+  @ApiResponse(responseCode = "401", description = "not authenticated / invalid credentials")
+  @ApiResponse(responseCode = "403", description = "not authorized, the current user has no privileges to read the tags")
+  @ApiResponse(
+    responseCode = "404",
+    description = "not found, no tag with the specified name available in the repository",
+    content = @Content(
+      mediaType = VndMediaType.ERROR_TYPE,
+      schema = @Schema(implementation = ErrorDto.class)
+    ))
+  @ApiResponse(
+    responseCode = "500",
+    description = "internal server error",
+    content = @Content(
+      mediaType = VndMediaType.ERROR_TYPE,
+      schema = @Schema(implementation = ErrorDto.class)
+    ))
  public Response get(@PathParam("namespace") String namespace, @PathParam("name") String name, @PathParam("tagName") String tagName) throws IOException {
    NamespaceAndName namespaceAndName = new NamespaceAndName(namespace, name);
    try (RepositoryService repositoryService = serviceFactory.create(namespaceAndName)) {
--- a/scm-webapp/src/main/java/sonia/scm/api/v2/resources/UIPluginResource.java
+++ b/scm-webapp/src/main/java/sonia/scm/api/v2/resources/UIPluginResource.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.plugin.PluginLoader;
 import sonia.scm.plugin.InstalledPlugin;
 import sonia.scm.security.AllowAnonymousAccess;
@@ -39,12 +40,23 @@ public class UIPluginResource {
   */
  @GET
  @Path("")
-  @StatusCodes({
-    @ResponseCode(code = 200, condition = "success"),
-    @ResponseCode(code = 500, condition = "internal server error")
-  })
-  @TypeHint(CollectionDto.class)
  @Produces(VndMediaType.UI_PLUGIN_COLLECTION)
+  @Operation(summary = "Collection of ui plugin bundles", description = "Returns a collection of installed plugins and their ui bundles.", hidden = true)
+  @ApiResponse(
+    responseCode = "200",
+    description = "success",
+    content = @Content(
+      mediaType = VndMediaType.UI_PLUGIN_COLLECTION,
+      schema = @Schema(implementation = CollectionDto.class)
+    )
+  )
+  @ApiResponse(
+    responseCode = "500",
+    description = "internal server error",
+    content = @Content(
+      mediaType = VndMediaType.ERROR_TYPE,
+      schema = @Schema(implementation = ErrorDto.class)
+    ))
  public Response getInstalledPlugins() {
    List<InstalledPlugin> plugins = pluginLoader.getInstalledPlugins()
      .stream()
@@ -63,13 +75,30 @@ public class UIPluginResource {
   */
  @GET
  @Path("{id}")
-  @StatusCodes({
-    @ResponseCode(code = 200, condition = "success"),
-    @ResponseCode(code = 404, condition = "not found"),
-    @ResponseCode(code = 500, condition = "internal server error")
-  })
-  @TypeHint(UIPluginDto.class)
  @Produces(VndMediaType.UI_PLUGIN)
+  @Operation(summary = "Get single ui plugin bundle", description = "Returns the installed plugin with the given id.", hidden = true)
+  @ApiResponse(
+    responseCode = "200",
+    description = "success",
+    content = @Content(
+      mediaType = VndMediaType.UI_PLUGIN,
+      schema = @Schema(implementation = UIPluginDto.class)
+    )
+  )
+  @ApiResponse(
+    responseCode = "404",
+    description = "not found",
+    content = @Content(
+      mediaType = VndMediaType.ERROR_TYPE,
+      schema = @Schema(implementation = ErrorDto.class)
+    ))
+  @ApiResponse(
+    responseCode = "500",
+    description = "internal server error",
+    content = @Content(
+      mediaType = VndMediaType.ERROR_TYPE,
+      schema = @Schema(implementation = ErrorDto.class)
+    ))
  public Response getInstalledPlugin(@PathParam("id") String id) {
    Optional<UIPluginDto> uiPluginDto = pluginLoader.getInstalledPlugins()
      .stream()
--- a/scm-webapp/src/main/java/sonia/scm/api/v2/resources/UserResource.java
+++ b/scm-webapp/src/main/java/sonia/scm/api/v2/resources/UserResource.java
@@ -54,7 +54,7 @@ public class UserResource {
  @GET
  @Path("")
  @Produces(VndMediaType.USER)
-  @Operation(summary = "Returns a single user", description = "Returns the user for the given id.", tags = "User")
+  @Operation(summary = "Get single user", description = "Returns the user for the given id.", tags = "User")
  @ApiResponse(
    responseCode = "200",
    description = "success",
@@ -92,7 +92,7 @@ public class UserResource {
   */
  @DELETE
  @Path("")
-  @Operation(summary = "Deletes a user", description = "Deletes the user for the given id.", tags = "User")
+  @Operation(summary = "Delete user", description = "Deletes the user with the given id.", tags = "User")
  @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 does not have the \"user\" privilege")
@@ -113,7 +113,7 @@ public class UserResource {
  @PUT
  @Path("")
  @Consumes(VndMediaType.USER)
-  @Operation(summary = "Modifies a user", description = "Modifies the user for the given id.", tags = "User")
+  @Operation(summary = "Update user", description = "Modifies the user for the given id.", tags = "User")
  @ApiResponse(responseCode = "204", description = "update success")
  @ApiResponse(responseCode = "400", description = "invalid body, e.g. illegal change of id/user name")
  @ApiResponse(responseCode = "401", description = "not authenticated / invalid credentials")