diff --git a/pom.xml b/pom.xml index 48e94c11de..535b9d9af8 100644 --- a/pom.xml +++ b/pom.xml @@ -266,6 +266,12 @@ ${jaxrs.version} + + io.swagger.core.v3 + swagger-annotations + 2.1.1 + + com.fasterxml.jackson.core jackson-core @@ -465,6 +471,12 @@ 2.8.2 + + io.openapitools.swagger + swagger-maven-plugin + 2.1.2 + + diff --git a/scm-webapp/src/main/java/sonia/scm/api/v2/resources/ErrorDto.java b/scm-core/src/main/java/sonia/scm/api/v2/resources/ErrorDto.java similarity index 100% rename from scm-webapp/src/main/java/sonia/scm/api/v2/resources/ErrorDto.java rename to scm-core/src/main/java/sonia/scm/api/v2/resources/ErrorDto.java diff --git a/scm-plugins/pom.xml b/scm-plugins/pom.xml index e6b2929bd2..b74effd8ce 100644 --- a/scm-plugins/pom.xml +++ b/scm-plugins/pom.xml @@ -61,6 +61,13 @@ provided + + + io.swagger.core.v3 + swagger-annotations + provided + + @@ -136,6 +143,37 @@ + + io.openapitools.swagger + swagger-maven-plugin + + + sonia.scm.api.v2.resources + + ${basedir}/target/classes/META-INF/scm + openapi + JSON,YAML + true + + + SCM-Manager Plugin REST-API + ${project.version} + + http://www.opensource.org/licenses/bsd-license.php + BSD + + + + + + + + generate + + + + + diff --git a/scm-plugins/scm-git-plugin/src/main/java/sonia/scm/api/v2/resources/GitConfigResource.java b/scm-plugins/scm-git-plugin/src/main/java/sonia/scm/api/v2/resources/GitConfigResource.java index 7cda4bc9d3..d3332d5a37 100644 --- a/scm-plugins/scm-git-plugin/src/main/java/sonia/scm/api/v2/resources/GitConfigResource.java +++ b/scm-plugins/scm-git-plugin/src/main/java/sonia/scm/api/v2/resources/GitConfigResource.java @@ -3,10 +3,17 @@ 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 sonia.scm.config.ConfigurationPermissions; import sonia.scm.repository.GitConfig; import sonia.scm.repository.GitRepositoryHandler; import sonia.scm.web.GitVndMediaType; +import sonia.scm.web.VndMediaType; import javax.inject.Inject; import javax.inject.Provider; @@ -14,13 +21,15 @@ import javax.ws.rs.Consumes; import javax.ws.rs.GET; import javax.ws.rs.PUT; import javax.ws.rs.Path; -import javax.ws.rs.PathParam; import javax.ws.rs.Produces; import javax.ws.rs.core.Response; /** * RESTful Web Service Resource to manage the configuration of the git plugin. */ +@OpenAPIDefinition(tags = { + @Tag(name = "Git", description = "Configuration for the git repository type") +}) @Path(GitConfigResource.GIT_CONFIG_PATH_V2) public class GitConfigResource { @@ -45,13 +54,24 @@ public class GitConfigResource { @GET @Path("") @Produces(GitVndMediaType.GIT_CONFIG) - @TypeHint(GitConfigDto.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 \"configuration:read:git\" privilege"), - @ResponseCode(code = 500, condition = "internal server error") - }) + @Operation(summary = "Git configuration", description = "Returns the global git configuration.", tags = "Git") + @ApiResponse( + responseCode = "200", + description = "success", + content = @Content( + mediaType = GitVndMediaType.GIT_CONFIG, + schema = @Schema(implementation = GitConfigDto.class) + ) + ) + @ApiResponse(responseCode = "401", description = "not authenticated / invalid credentials") + @ApiResponse(responseCode = "403", description = "not authorized, the current user does not have the \"configuration:read:git\" privilege") + @ApiResponse( + responseCode = "500", + description = "internal server error", + content = @Content( + mediaType = VndMediaType.ERROR_TYPE, + schema = @Schema(implementation = ErrorDto.class) + )) public Response get() { GitConfig config = repositoryHandler.getConfig(); @@ -80,7 +100,20 @@ public class GitConfigResource { @ResponseCode(code = 403, condition = "not authorized, the current user does not have the \"configuration:write:git\" privilege"), @ResponseCode(code = 500, condition = "internal server error") }) - @TypeHint(TypeHint.NO_CONTENT.class) + @Operation(summary = "Modify git configuration", description = "Modifies the global git configuration.", tags = "Git") + @ApiResponse( + responseCode = "204", + description = "update success" + ) + @ApiResponse(responseCode = "401", description = "not authenticated / invalid credentials") + @ApiResponse(responseCode = "403", description = "not authorized, the current user does not have the \"configuration:write:git\" privilege") + @ApiResponse( + responseCode = "500", + description = "internal server error", + content = @Content( + mediaType = VndMediaType.ERROR_TYPE, + schema = @Schema(implementation = ErrorDto.class) + )) public Response update(GitConfigDto configDto) { GitConfig config = dtoToConfigMapper.map(configDto); @@ -94,7 +127,7 @@ public class GitConfigResource { } @Path("{namespace}/{name}") - public GitRepositoryConfigResource getRepositoryConfig(@PathParam("namespace") String namespace, @PathParam("name") String name) { + public GitRepositoryConfigResource getRepositoryConfig() { return gitRepositoryConfigResource.get(); } } diff --git a/scm-plugins/scm-git-plugin/src/main/java/sonia/scm/api/v2/resources/GitRepositoryConfigResource.java b/scm-plugins/scm-git-plugin/src/main/java/sonia/scm/api/v2/resources/GitRepositoryConfigResource.java index 175caf8840..88a9c5d669 100644 --- a/scm-plugins/scm-git-plugin/src/main/java/sonia/scm/api/v2/resources/GitRepositoryConfigResource.java +++ b/scm-plugins/scm-git-plugin/src/main/java/sonia/scm/api/v2/resources/GitRepositoryConfigResource.java @@ -2,6 +2,10 @@ package sonia.scm.api.v2.resources; import com.webcohesion.enunciate.metadata.rs.ResponseCode; import com.webcohesion.enunciate.metadata.rs.StatusCodes; +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.slf4j.Logger; import org.slf4j.LoggerFactory; import sonia.scm.repository.GitRepositoryConfig; @@ -11,6 +15,7 @@ import sonia.scm.repository.RepositoryManager; import sonia.scm.repository.RepositoryPermissions; import sonia.scm.store.ConfigurationStore; import sonia.scm.web.GitVndMediaType; +import sonia.scm.web.VndMediaType; import javax.inject.Inject; import javax.ws.rs.Consumes; @@ -42,13 +47,31 @@ public class GitRepositoryConfigResource { @GET @Path("/") @Produces(GitVndMediaType.GIT_REPOSITORY_CONFIG) - @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 config"), - @ResponseCode(code = 404, condition = "not found, no repository with the specified namespace and name available"), - @ResponseCode(code = 500, condition = "internal server error") - }) + @Operation(summary = "Git repository configuration", description = "Returns the repository related git configuration.", tags = "Git") + @ApiResponse( + responseCode = "200", + description = "success", + content = @Content( + mediaType = GitVndMediaType.GIT_REPOSITORY_CONFIG, + schema = @Schema(implementation = GitRepositoryConfigDto.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 config") + @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", + content = @Content( + mediaType = VndMediaType.ERROR_TYPE, + schema = @Schema(implementation = ErrorDto.class) + )) public Response getRepositoryConfig(@PathParam("namespace") String namespace, @PathParam("name") String name) { Repository repository = getRepository(namespace, name); RepositoryPermissions.read(repository).check(); @@ -61,13 +84,27 @@ public class GitRepositoryConfigResource { @PUT @Path("/") @Consumes(GitVndMediaType.GIT_REPOSITORY_CONFIG) - @StatusCodes({ - @ResponseCode(code = 204, condition = "update success"), - @ResponseCode(code = 401, condition = "not authenticated / invalid credentials"), - @ResponseCode(code = 403, condition = "not authorized, the current user does not have the privilege to change this repositories config"), - @ResponseCode(code = 404, condition = "not found, no repository with the specified namespace and name available/name available"), - @ResponseCode(code = 500, condition = "internal server error") - }) + @Operation(summary = "Modifies git repository configuration", description = "Modifies the repository related git configuration.", tags = "Git") + @ApiResponse( + responseCode = "204", + description = "update success" + ) + @ApiResponse(responseCode = "401", description = "not authenticated / invalid credentials") + @ApiResponse(responseCode = "403", description = "not authorized, the current user does not have the privilege to change this repositories config") + @ApiResponse( + responseCode = "404", + description = "not found, no repository with the specified namespace and name available/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 setRepositoryConfig(@PathParam("namespace") String namespace, @PathParam("name") String name, GitRepositoryConfigDto dto) { Repository repository = getRepository(namespace, name); RepositoryPermissions.custom("git", repository).check(); diff --git a/scm-webapp/pom.xml b/scm-webapp/pom.xml index 4520700dbc..d8068f1bb8 100644 --- a/scm-webapp/pom.xml +++ b/scm-webapp/pom.xml @@ -481,7 +481,6 @@ io.openapitools.swagger swagger-maven-plugin - 2.1.2 sonia.scm.api.v2.resources