Create openapi docs for me endpoint and changesets

2025-11-12 16:35:45 +01:00 · 2020-02-18 17:20:23 +01:00
parent 5364e8682d
commit dc83b50095
3 changed files with 142 additions and 66 deletions
--- 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,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 lombok.extern.slf4j.Slf4j;
 import sonia.scm.PageResult;
 import sonia.scm.repository.Changeset;
@@ -42,17 +43,82 @@ 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("")
-  @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")
-  })
  @Produces(VndMediaType.CHANGESET_COLLECTION)
-  @TypeHint(CollectionDto.class)
+  @Operation(summary = "Specific changeset", description = "Returns a specific changeset.", 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 getAll(@PathParam("namespace") String namespace, @PathParam("name") String name, @DefaultValue("0") @QueryParam("page") int page,
                         @DefaultValue("10") @QueryParam("pageSize") int pageSize) throws IOException {
    try (RepositoryService repositoryService = serviceFactory.create(new NamespaceAndName(namespace, name))) {
@@ -75,35 +141,4 @@ public class ChangesetRootResource {
      }
    }
  }
-
-  @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 changeset with the specified id is available in the repository"),
-    @ResponseCode(code = 500, condition = "internal server error")
-  })
-  @Produces(VndMediaType.CHANGESET)
-  @TypeHint(ChangesetDto.class)
-  @Path("{id}")
-  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/FileHistoryRootResource.java
+++ b/scm-webapp/src/main/java/sonia/scm/api/v2/resources/FileHistoryRootResource.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 lombok.extern.slf4j.Slf4j;
 import sonia.scm.PageResult;
 import sonia.scm.repository.Changeset;
@@ -54,15 +55,32 @@ public class FileHistoryRootResource {
   */
  @GET
  @Path("{revision}/{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 changeset"),
-    @ResponseCode(code = 404, condition = "not found, no changesets available in the repository"),
-    @ResponseCode(code = 500, condition = "internal server error")
-  })
  @Produces(VndMediaType.CHANGESET_COLLECTION)
-  @TypeHint(CollectionDto.class)
+  @Operation(summary = "Changesets to given file", description = "Get all changesets related to the given file starting with the given revision.", 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 getAll(@PathParam("namespace") String namespace, @PathParam("name") String name,
                         @PathParam("revision") String revision,
                         @PathParam("path") String path,
--- a/scm-webapp/src/main/java/sonia/scm/api/v2/resources/MeResource.java
+++ b/scm-webapp/src/main/java/sonia/scm/api/v2/resources/MeResource.java
@@ -3,6 +3,12 @@ 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.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 org.apache.shiro.authc.credential.PasswordService;
 import sonia.scm.user.UserManager;
 import sonia.scm.web.VndMediaType;
@@ -23,11 +29,13 @@ import javax.ws.rs.core.UriInfo;
 /**
 * RESTful Web Service Resource to get currently logged in users.
 */
+@OpenAPIDefinition(tags = {
+  @Tag(name = "Me", description = "Me related endpoints")
+})
@Path(MeResource.ME_PATH_V2)
 public class MeResource {

  static final String ME_PATH_V2 = "v2/me/";
-
  private final MeDtoFactory meDtoFactory;
  private final UserManager userManager;
  private final PasswordService passwordService;
@@ -45,12 +53,23 @@ public class MeResource {
  @GET
  @Path("")
  @Produces(VndMediaType.ME)
-  @TypeHint(MeDto.class)
-  @StatusCodes({
-    @ResponseCode(code = 200, condition = "success"),
-    @ResponseCode(code = 401, condition = "not authenticated / invalid credentials"),
-    @ResponseCode(code = 500, condition = "internal server error")
-  })
+  @Operation(summary = "Current user", description = "Returns the currently logged in user or a 401 if user is not logged in.", tags = "Me")
+  @ApiResponse(
+    responseCode = "200",
+    description = "success",
+    content = @Content(
+      mediaType = VndMediaType.ME,
+      schema = @Schema(implementation = MeDto.class)
+    )
+  )
+  @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 get(@Context Request request, @Context UriInfo uriInfo) {
    return Response.ok(meDtoFactory.create()).build();
  }
@@ -60,13 +79,17 @@ public class MeResource {
   */
  @PUT
  @Path("password")
-  @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.PASSWORD_CHANGE)
+  @Operation(summary = "Change password", description = "Change password of the current user.", tags = "Me")
+  @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 changePassword(@Valid PasswordChangeDto passwordChange) {
    userManager.changePasswordForLoggedInUser(
      passwordService.encryptPassword(passwordChange.getOldPassword()),