From 09beb8cd3bd545f14067b20a648b7445df084359 Mon Sep 17 00:00:00 2001 From: Florian Scholdei Date: Mon, 1 Aug 2022 21:42:21 +0200 Subject: [PATCH] Add api doc for cli and more (#2101) --- .../scm/legacy/LegacyRepositoryService.java | 6 +++ .../scm/api/v2/resources/CliResource.java | 38 +++++++++++++++++-- .../resources/RepositoryImportResource.java | 21 ++++++++++ 3 files changed, 61 insertions(+), 4 deletions(-) diff --git a/scm-plugins/scm-legacy-plugin/src/main/java/sonia/scm/legacy/LegacyRepositoryService.java b/scm-plugins/scm-legacy-plugin/src/main/java/sonia/scm/legacy/LegacyRepositoryService.java index 826e072b8e..e754543c8b 100644 --- a/scm-plugins/scm-legacy-plugin/src/main/java/sonia/scm/legacy/LegacyRepositoryService.java +++ b/scm-plugins/scm-legacy-plugin/src/main/java/sonia/scm/legacy/LegacyRepositoryService.java @@ -25,6 +25,7 @@ package sonia.scm.legacy; import com.google.inject.Inject; +import io.swagger.v3.oas.annotations.Operation; import sonia.scm.NotFoundException; import sonia.scm.repository.Repository; import sonia.scm.repository.RepositoryManager; @@ -48,6 +49,11 @@ public class LegacyRepositoryService { @GET @Path("{id}") @Produces(MediaType.APPLICATION_JSON) + @Operation( + summary = "Repository namespace and name", + description = "Returns the repository namespace and name", + tags = "Repository" + ) public NamespaceAndNameDto getNameAndNamespaceForRepositoryId(@PathParam("id") String repositoryId) { Repository repo = repositoryManager.get(repositoryId); if (repo == null) { diff --git a/scm-webapp/src/main/java/sonia/scm/api/v2/resources/CliResource.java b/scm-webapp/src/main/java/sonia/scm/api/v2/resources/CliResource.java index b781e00cac..427873df16 100644 --- a/scm-webapp/src/main/java/sonia/scm/api/v2/resources/CliResource.java +++ b/scm-webapp/src/main/java/sonia/scm/api/v2/resources/CliResource.java @@ -24,12 +24,15 @@ 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.responses.ApiResponse; +import io.swagger.v3.oas.annotations.tags.Tag; import lombok.Data; import org.apache.shiro.SecurityUtils; import sonia.scm.cli.CliProcessor; -import sonia.scm.cli.Client; import sonia.scm.cli.JsonStreamingCliContext; -import sonia.scm.cli.UserAgentClientParser; import sonia.scm.security.ApiKeyService; import javax.inject.Inject; @@ -46,8 +49,11 @@ import javax.ws.rs.core.Response; import javax.ws.rs.core.StreamingOutput; import java.util.List; -import static sonia.scm.cli.UserAgentClientParser.*; +import static sonia.scm.cli.UserAgentClientParser.parse; +@OpenAPIDefinition(tags = { + @Tag(name = "CLI", description = "Command-line interface related endpoints") +}) @Path("v2/cli") public class CliResource { @@ -62,6 +68,16 @@ public class CliResource { @POST @Path("exec") + @Consumes(MediaType.APPLICATION_OCTET_STREAM) + @Operation(summary = "Execute", description = "Execute commands", tags = "CLI") + @ApiResponse( + responseCode = "200", + description = "success", + content = @Content( + mediaType = MediaType.APPLICATION_OCTET_STREAM + ) + ) + @ApiResponse(responseCode = "401", description = "not authenticated / invalid credentials") public StreamingOutput exec(@QueryParam("args") List args, @Context HttpServletRequest request) { return outputStream -> { try (JsonStreamingCliContext context = new JsonStreamingCliContext( @@ -77,8 +93,18 @@ public class CliResource { } @POST - @Consumes(MediaType.APPLICATION_JSON) @Path("login") + @Consumes(MediaType.APPLICATION_JSON) + @Operation(summary = "Log in", description = "Create api key to connect to the SCM-Manager server", tags = "CLI") + @ApiResponse( + responseCode = "200", + description = "success", + content = @Content( + mediaType = MediaType.APPLICATION_JSON + ) + ) + @ApiResponse(responseCode = "401", description = "not authenticated / invalid credentials") + @ApiResponse(responseCode = "500", description = "internal server error") public Response login(CliAuthenticationDto auth) { String username = SecurityUtils.getSubject().getPrincipal().toString(); ApiKeyService.CreationResult newKey = service.createNewKey(username, auth.getApiKey(), "*"); @@ -87,6 +113,10 @@ public class CliResource { @DELETE @Path("logout/{apiKey}") + @Operation(summary = "Log out", description = "Remove api key from SCM-Manager server", tags = "CLI") + @ApiResponse(responseCode = "204", description = "delete success or nothing to delete") + @ApiResponse(responseCode = "400", description = "bad request, required parameter is missing") + @ApiResponse(responseCode = "401", description = "not authenticated / invalid credentials") public Response logout(@PathParam("apiKey") String apiKeyName) { String username = SecurityUtils.getSubject().getPrincipal().toString(); service.getKeys(username) diff --git a/scm-webapp/src/main/java/sonia/scm/api/v2/resources/RepositoryImportResource.java b/scm-webapp/src/main/java/sonia/scm/api/v2/resources/RepositoryImportResource.java index 853263d9a7..b3b62e24b7 100644 --- a/scm-webapp/src/main/java/sonia/scm/api/v2/resources/RepositoryImportResource.java +++ b/scm-webapp/src/main/java/sonia/scm/api/v2/resources/RepositoryImportResource.java @@ -263,6 +263,27 @@ public class RepositoryImportResource { @GET @Path("log/{logId}") @Produces(MediaType.TEXT_PLAIN) + @Operation( + summary = "Import log", + description = "Returns the import log", + tags = "Repository" + ) + @ApiResponse( + responseCode = "200", + description = "success", + content = @Content( + mediaType = MediaType.TEXT_PLAIN + ) + ) + @ApiResponse(responseCode = "401", description = "not authenticated / invalid credentials") + @ApiResponse( + responseCode = "404", + description = "not found, no log found for the given id", + content = @Content( + mediaType = VndMediaType.ERROR_TYPE, + schema = @Schema(implementation = ErrorDto.class) + ) + ) public StreamingOutput getImportLog(@PathParam("logId") String logId) throws IOException { importLoggerFactory.checkCanReadLog(logId); return out -> importLoggerFactory.getLog(logId, out);