create openapi docs for scm-git-plugin

pom.xml

@@ -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>
 

scm-plugins/pom.xml

@@ -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>
 

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)
+  @Operation(summary = "Git configuration", description = "Returns the global git configuration.", tags = "Git")
-  @StatusCodes({
+  @ApiResponse(
-    @ResponseCode(code = 200, condition = "success"),
+    responseCode = "200",
-    @ResponseCode(code = 401, condition = "not authenticated / invalid credentials"),
+    description = "success",
-    @ResponseCode(code = 403, condition = "not authorized, the current user does not have the \"configuration:read:git\" privilege"),
+    content = @Content(
-    @ResponseCode(code = 500, condition = "internal server error")
+      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();
   }
 }

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({
+  @Operation(summary = "Git repository configuration", description = "Returns the repository related git configuration.", tags = "Git")
-    @ResponseCode(code = 200, condition = "success"),
+  @ApiResponse(
-    @ResponseCode(code = 401, condition = "not authenticated / invalid credentials"),
+    responseCode = "200",
-    @ResponseCode(code = 403, condition = "not authorized, the current user has no privileges to read the repository config"),
+    description = "success",
-    @ResponseCode(code = 404, condition = "not found, no repository with the specified namespace and name available"),
+    content = @Content(
-    @ResponseCode(code = 500, condition = "internal server error")
+      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({
+  @Operation(summary = "Modifies git repository configuration", description = "Modifies the repository related git configuration.", tags = "Git")
-    @ResponseCode(code = 204, condition = "update success"),
+  @ApiResponse(
-    @ResponseCode(code = 401, condition = "not authenticated / invalid credentials"),
+    responseCode = "204",
-    @ResponseCode(code = 403, condition = "not authorized, the current user does not have the privilege to change this repositories config"),
+    description = "update success"
-    @ResponseCode(code = 404, condition = "not found, no repository with the specified namespace and name available/name available"),
+  )
-    @ResponseCode(code = 500, condition = "internal server error")
+  @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();

scm-webapp/pom.xml

@@ -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>