Nemcio/SCM-Manager
1
0
Fork 0
mirror of https://github.com/scm-manager/scm-manager.git synced 2025-11-12 16:35:45 +01:00
Code Issues Packages Projects Releases Activity

create openapi docs for scm-git-plugin

Browse Source
This commit is contained in:
Eduard Heimbuch
2020-02-17 14:09:26 +01:00
parent 7243f3d5a5
commit b7e95f3cc4
6 changed files with 144 additions and 25 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
pom.xml
View File

@@ -266,6 +266,12 @@
<version>${jaxrs.version}</version>
</dependency>
<dependency>
<groupId>io.swagger.core.v3</groupId>
<artifactId>swagger-annotations</artifactId>
<version>2.1.1</version>
</dependency>
<dependency>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-core</artifactId>
@@ -465,6 +471,12 @@
<version>2.8.2</version>
</plugin>
<plugin>
<groupId>io.openapitools.swagger</groupId>
<artifactId>swagger-maven-plugin</artifactId>
<version>2.1.2</version>
</plugin>
</plugins>
</pluginManagement>

0
scm-webapp/src/main/java/sonia/scm/api/v2/resources/ErrorDto.java → scm-core/src/main/java/sonia/scm/api/v2/resources/ErrorDto.java
View File

38
scm-plugins/pom.xml
View File

@@ -61,6 +61,13 @@
<scope>provided</scope>
</dependency>
<!-- openapi documentation -->
<dependency>
<groupId>io.swagger.core.v3</groupId>
<artifactId>swagger-annotations</artifactId>
<scope>provided</scope>
</dependency>
<!-- test scope -->
<dependency>
@@ -136,6 +143,37 @@
</configuration>
</plugin>
<plugin>
<groupId>io.openapitools.swagger</groupId>
<artifactId>swagger-maven-plugin</artifactId>
<configuration>
<resourcePackages>
<resourcePackage>sonia.scm.api.v2.resources</resourcePackage>
</resourcePackages>
<outputDirectory>${basedir}/target/classes/META-INF/scm</outputDirectory>
<outputFilename>openapi</outputFilename>
<outputFormats>JSON,YAML</outputFormats>
<prettyPrint>true</prettyPrint>
<swaggerConfig>
<info>
<title>SCM-Manager Plugin REST-API</title>
<version>${project.version}</version>
<license>
<url>http://www.opensource.org/licenses/bsd-license.php</url>
<name>BSD</name>
</license>
</info>
</swaggerConfig>
</configuration>
<executions>
<execution>
<goals>
<goal>generate</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</build>

53
scm-plugins/scm-git-plugin/src/main/java/sonia/scm/api/v2/resources/GitConfigResource.java
View File

@@ -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();
}
}

65
scm-plugins/scm-git-plugin/src/main/java/sonia/scm/api/v2/resources/GitRepositoryConfigResource.java
View File

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

1
scm-webapp/pom.xml
View File

@@ -481,7 +481,6 @@
<plugin>
<groupId>io.openapitools.swagger</groupId>
<artifactId>swagger-maven-plugin</artifactId>
<version>2.1.2</version>
<configuration>
<resourcePackages>
<resourcePackage>sonia.scm.api.v2.resources</resourcePackage>