bootstrap openapi documentation

scm-webapp/src/main/java/sonia/scm/api/v2/resources/AuthenticationResource.java

@@ -3,6 +3,10 @@ package sonia.scm.api.v2.resources;
 import com.google.inject.Inject;
 import com.webcohesion.enunciate.metadata.rs.ResponseCode;
 import com.webcohesion.enunciate.metadata.rs.StatusCodes;
+import io.swagger.v3.oas.annotations.enums.SecuritySchemeIn;
+import io.swagger.v3.oas.annotations.enums.SecuritySchemeType;
+import io.swagger.v3.oas.annotations.security.SecurityScheme;
+import io.swagger.v3.oas.annotations.security.SecuritySchemes;
 import org.apache.shiro.SecurityUtils;
 import org.apache.shiro.authc.AuthenticationException;
 import org.apache.shiro.subject.Subject;
@@ -19,6 +23,22 @@ import javax.ws.rs.core.Response;
 import java.net.URI;
 import java.util.Optional;
 
+@SecuritySchemes({
+  @SecurityScheme(
+    name = "Basic Authentication",
+    description = "HTTP Basic authentication with username and password",
+    scheme = "Basic",
+    type = SecuritySchemeType.HTTP
+  ),
+  @SecurityScheme(
+    name = "Bearer Token Authentication",
+    in = SecuritySchemeIn.HEADER,
+    paramName = "Authorization",
+    scheme = "Bearer",
+    bearerFormat = "JWT",
+    type = SecuritySchemeType.APIKEY
+  )
+})
 @Path(AuthenticationResource.PATH)
 @AllowAnonymousAccess
 public class AuthenticationResource {

scm-webapp/src/main/java/sonia/scm/api/v2/resources/RepositoryResource.java

@@ -3,6 +3,10 @@ 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 sonia.scm.repository.NamespaceAndName;
 import sonia.scm.repository.Repository;
 import sonia.scm.repository.RepositoryManager;
@@ -87,14 +91,39 @@ public class RepositoryResource {
   @GET
   @Path("")
   @Produces(VndMediaType.REPOSITORY)
-  @TypeHint(RepositoryDto.class)
-  @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"),
-    @ResponseCode(code = 404, condition = "not found, no repository with the specified name available in the namespace"),
-    @ResponseCode(code = 500, condition = "internal server error")
-  })
+  @Operation(summary = "Returns a single repository", description = "Returns the repository for the given namespace and name.", tags = "Repository")
+  @ApiResponse(
+    responseCode = "200",
+    description = "success",
+    content = @Content(
+      mediaType = VndMediaType.REPOSITORY,
+      schema = @Schema(implementation = RepositoryDto.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"
+  )
+  @ApiResponse(
+    responseCode = "404",
+    description = "not found, no repository with the specified name available in the namespace",
+    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){
     return adapter.get(loadBy(namespace, name), repositoryToDtoMapper::map);
   }
@@ -168,7 +197,7 @@ public class RepositoryResource {
   }
 
   @Path("branches/")
-  public BranchRootResource branches(@PathParam("namespace") String namespace, @PathParam("name") String name) {
+  public BranchRootResource branches() {
     return branchRootResource.get();
   }
 

scm-webapp/src/main/java/sonia/scm/api/v2/resources/RepositoryRootResource.java

@@ -1,12 +1,20 @@
 package sonia.scm.api.v2.resources;
 
+import io.swagger.v3.oas.annotations.OpenAPIDefinition;
+import io.swagger.v3.oas.annotations.tags.Tag;
+
 import javax.inject.Inject;
 import javax.inject.Provider;
 import javax.ws.rs.Path;
 
 /**
- *  RESTful Web Service Resource to manage repositories.
+ * RESTful Web Service Resource to manage repositories.
  */
+@OpenAPIDefinition(
+  tags = {
+    @Tag(name = "Repository", description = "Repository related endpoints")
+  }
+)
 @Path(RepositoryRootResource.REPOSITORIES_PATH_V2)
 public class RepositoryRootResource {
   static final String REPOSITORIES_PATH_V2 = "v2/repositories/";