feat(dashboard): add OpenAPI spec generation and Swagger UI (#161)

* feat(dashboard): add OpenAPI spec generation and Swagger UI

Adds /api/openapi.json and /api/openapi.yaml endpoints generated from
Spring MVC route metadata at startup, plus a Swagger UI browser at
/swagger-ui backed by a custom HTML page that bypasses swagger-initializer.js.

Uses swagger-core-jakarta (no JAX-RS dep) + RequestMappingHandlerMapping
to build the OAS3 spec without springdoc or Spring Boot. WebJar paths are
versioned and injected via Gradle token expansion at build time.

All controllers annotated with @tag and @operation for a clean spec
grouped by System, Auth, Users, Repos, Push, Providers, Profile, Admin.

closes #121

* feat(dashboard): add GET /api root endpoint returning version and API docs link

Adds a public /api endpoint (no auth) that returns the app version and
the path to the OpenAPI spec. Useful as a quick sanity-check that the API
is reachable. SecurityConfig updated to permit /api alongside the other
public endpoints.

* fix(ci): replace depcheck with CycloneDX SBOM + Grype for Gradle CVE scanning

OWASP dependency-check is failing due to a breaking NVD API change
(nanosecond-precision timestamps not handled by the Jackson deserializer;
dependency-check/DependencyCheck#8425). No fix is available yet.

Replaces the depcheck job with:
- org.cyclonedx.bom 3.2.4 plugin generating a CycloneDX SBOM at build time
- anchore/scan-action scanning the SBOM with Grype (same scanner used for
  npm and container image scans)

Also adds failOnError=false to the dependencyCheck config so local runs
with the OWASP plugin don't abort when NVD is unavailable.

Renames CI job display names to be tool-agnostic:
- 'CVE / Dependency Check (Gradle)' -> 'CVE / Gradle'
- 'CVE / Grype (npm)' -> 'CVE / npm'
- 'Grype / Container Scan' -> 'Container Scan'

Branch protection and release gate rulesets updated to match new names.

Author: coopernetes

.github/workflows/cve.yml

@@ -11,7 +11,7 @@ on:
 
 jobs:
   grype-npm:
-    name: CVE / Grype (npm)
+    name: CVE / npm
     runs-on: ubuntu-latest
     permissions:
       contents: read
@@ -36,9 +36,12 @@ jobs:
         with:
           sarif_file: ${{ steps.scan.outputs.sarif }}
 
-  depcheck:
-    name: CVE / Dependency Check (Gradle)
+  grype-gradle:
+    name: CVE / Gradle
     runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      security-events: write
     steps:
       - name: Checkout
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # ratchet:actions/checkout@v6
@@ -48,32 +51,29 @@ jobs:
           java-version: 21
           cache: gradle
 
-      - uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # ratchet:actions/setup-node@v6
+      - name: Generate SBOM
+        run: ./gradlew cyclonedxBom -PskipFrontend
+
+      - name: Scan SBOM with Grype
+        uses: anchore/scan-action@e1165082ffb1fe366ebaf02d8526e7c4989ea9d2 # ratchet:anchore/scan-action@v7
+        id: scan
         with:
-          node-version: '24.14.1'
-          cache: npm
-          cache-dependency-path: git-proxy-java-dashboard/frontend/package-lock.json
+          sbom: build/reports/cyclonedx/bom.json
+          fail-build: true
+          severity-cutoff: high
+          only-fixed: true
+          config: .grype.yaml
 
-      - name: Build project with Gradle
-        run: ./gradlew clean testClasses
-      - name: Cache CVE data
-        id: cache-cve
-        uses: actions/cache@668228422ae6a00e4ad889ee87cd7109ec5666a7 # ratchet:actions/cache@v5
+      - name: Upload SARIF report
+        if: ${{ always() }}
+        uses: github/codeql-action/upload-sarif@c10b8064de6f491fea524254123dbe5e09572f13 # ratchet:github/codeql-action/upload-sarif@v4
         with:
-          path: ~/.gradle/dependency-check-data/
-          key: depcheck-db-${{ github.run_id }}
-          restore-keys: depcheck-db-
-      - name: Depcheck
-        run: ./gradlew dependencyCheckAggregate --info
-        timeout-minutes: 180
-        env:
-          NVD_API_KEY: ${{ secrets.NVD_API_KEY }}
-          OSS_INDEX_USERNAME: ${{ secrets.OSS_INDEX_USERNAME }}
-          OSS_INDEX_TOKEN: ${{ secrets.OSS_INDEX_TOKEN }}
+          sarif_file: ${{ steps.scan.outputs.sarif }}
 
-      - name: Upload Test results
+      - name: Upload SBOM
         if: ${{ always() }}
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # ratchet:actions/upload-artifact@v7
         with:
-          name: Depcheck report
-          path: ${{ github.workspace }}/build/reports/dependency-check*
+          name: sbom-gradle
+          path: build/reports/cyclonedx/bom.json
+          retention-days: 30

.github/workflows/grype.yml

@@ -15,7 +15,7 @@ on:
 
 jobs:
   grype:
-    name: Grype / Container Scan
+    name: Container Scan
     runs-on: ubuntu-latest
     steps:
       - name: Checkout

build.gradle

@@ -1,6 +1,7 @@
 plugins {
     id 'com.diffplug.spotless' version '8.4.0' apply false
     id 'org.owasp.dependencycheck' version '12.2.0'
+    id 'org.cyclonedx.bom' version '3.2.4'
     id 'com.github.node-gradle.node' version '7.1.0' apply false
 }
 
@@ -61,6 +62,10 @@ ext {
     // Gitleaks (bundled binary)
     gitleaksVersion = '8.21.2'
 
+    // OpenAPI spec generation
+    swaggerCoreVersion = '2.2.48'
+    swaggerUiVersion = '5.21.0'
+
 }
 
 allprojects {
@@ -80,10 +85,15 @@ allprojects {
         analyzers.ossIndex.url = 'https://api.guide.sonatype.com/'
         failBuildOnCVSS = 5
         suppressionFile = rootProject.file('gradle-suppressions.xml').toString()
+        failOnError = false
     }
 }
 
 
+cyclonedxBom {
+    projectType = 'application'
+}
+
 tasks.register('installGitHooks') {
     group = 'build setup'
     description = 'Configures git to use the .githooks/ directory (run once after cloning).'

git-proxy-java-dashboard/build.gradle

@@ -98,6 +98,14 @@ tasks.named('processResources') {
     if (!project.hasProperty('skipFrontend')) {
         dependsOn tasks.named('copyFrontend')
     }
+    // Inject the project version into version.properties so OpenApiController can read it at runtime.
+    filesMatching('version.properties') {
+        expand(appVersion: project.version)
+    }
+    // Inject the Swagger UI WebJar version into swagger-ui.html so the asset paths are correct.
+    filesMatching('**/swagger-ui.html') {
+        expand(swaggerUiVersion: swaggerUiVersion)
+    }
 }
 
 tasks.named('run') {
@@ -161,6 +169,12 @@ dependencies {
     // MongoDB driver — compile-scoped because MongoSessionRepository uses the sync client directly.
     implementation "org.mongodb:mongodb-driver-sync:${mongoVersion}"
 
+    // OpenAPI spec generation — core model + YAML/JSON serialisation only (no JAX-RS required).
+    // The spec is built programmatically from Spring's RequestMappingHandlerMapping.
+    implementation "io.swagger.core.v3:swagger-core-jakarta:${swaggerCoreVersion}"
+    // Swagger UI static assets served from /webjars/** via the WebJar resource handler.
+    runtimeOnly "org.webjars:swagger-ui:${swaggerUiVersion}"
+
     // Gestalt config (needed to catch GestaltException from GitProxyConfigLoader)
     implementation "com.github.gestalt-config:gestalt-core:${gestaltVersion}"
 

git-proxy-java-dashboard/src/main/java/org/finos/gitproxy/dashboard/GitProxyWithDashboardApplication.java

@@ -120,9 +120,10 @@ public void lifeCycleStopping(LifeCycle event) {
         server.start();
 
         log.info("JGit Proxy with Dashboard started on port {}", connector.getPort());
-        log.info("  Dashboard: http://localhost:{}/dashboard/", connector.getPort());
-        log.info("  API:       http://localhost:{}/api/push", connector.getPort());
-        log.info("  Health:    http://localhost:{}/api/health", connector.getPort());
+        log.info("  Dashboard:  http://localhost:{}/dashboard/", connector.getPort());
+        log.info("  API:        http://localhost:{}/api", connector.getPort());
+        log.info("  Health:     http://localhost:{}/api/health", connector.getPort());
+        log.info("  Swagger UI: http://localhost:{}/swagger-ui", connector.getPort());
 
         server.join();
     }

git-proxy-java-dashboard/src/main/java/org/finos/gitproxy/dashboard/SecurityConfig.java

@@ -147,7 +147,13 @@ public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Excepti
                 : new String[] {"/api/**", "/login", "/logout"};
 
         http.securityMatcher(protectedPaths)
-                .authorizeHttpRequests(auth -> auth.requestMatchers("/api/runtime-config", "/api/health")
+                .authorizeHttpRequests(auth -> auth.requestMatchers(
+                                "/api",
+                                "/api/runtime-config",
+                                "/api/health",
+                                "/api/openapi.yaml",
+                                "/api/openapi.json",
+                                "/webjars/**")
                         .permitAll()
                         .requestMatchers("/api/users", "/api/users/**")
                         .hasRole("ADMIN")

git-proxy-java-dashboard/src/main/java/org/finos/gitproxy/dashboard/SpringWebConfig.java

@@ -26,6 +26,10 @@ public void configureMessageConverters(HttpMessageConverters.ServerBuilder build
 
     @Override
     public void addResourceHandlers(ResourceHandlerRegistry registry) {
+        // WebJar assets (Swagger UI) served at /webjars/** with versioned paths.
+        registry.addResourceHandler("/webjars/**")
+                .addResourceLocations("classpath:/META-INF/resources/webjars/")
+                .resourceChain(true);
         registry.addResourceHandler("/**")
                 .addResourceLocations("classpath:/static/")
                 .resourceChain(true);

git-proxy-java-dashboard/src/main/java/org/finos/gitproxy/dashboard/controller/AuthController.java

@@ -1,5 +1,7 @@
 package org.finos.gitproxy.dashboard.controller;
 
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import java.util.ArrayList;
 import java.util.List;
 import java.util.Map;
@@ -14,6 +16,7 @@
 import org.springframework.web.bind.annotation.RequestMapping;
 import org.springframework.web.bind.annotation.RestController;
 
+@Tag(name = "Auth", description = "Current user profile and session information")
 @RestController
 @RequestMapping("/api")
 public class AuthController {
@@ -28,6 +31,7 @@ public class AuthController {
      * Returns the currently authenticated user's full profile: username, emails (with verified flag), SCM identities,
      * authorities, and repo permissions.
      */
+    @Operation(operationId = "getCurrentUser", summary = "Get the authenticated user's profile")
     @GetMapping("/me")
     public Map<String, Object> me() {
         Authentication auth = SecurityContextHolder.getContext().getAuthentication();

git-proxy-java-dashboard/src/main/java/org/finos/gitproxy/dashboard/controller/ConfigReloadController.java

@@ -1,5 +1,7 @@
 package org.finos.gitproxy.dashboard.controller;
 
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import java.util.Map;
 import org.finos.gitproxy.jetty.reload.LiveConfigLoader;
 import org.finos.gitproxy.jetty.reload.LiveConfigLoader.Section;
@@ -30,13 +32,15 @@
  *
  * <p>This endpoint requires {@code ROLE_ADMIN}.
  */
+@Tag(name = "Admin", description = "Administrative operations — requires ROLE_ADMIN")
 @RestController
 @RequestMapping("/api/config")
 public class ConfigReloadController {
 
     @Autowired
     private LiveConfigLoader liveConfigLoader;
 
+    @Operation(operationId = "reloadConfig", summary = "Trigger a live config reload")
     @PostMapping("/reload")
     public ResponseEntity<Map<String, String>> reload(
             @RequestParam(name = "section", defaultValue = "all") String sectionParam) {

git-proxy-java-dashboard/src/main/java/org/finos/gitproxy/dashboard/controller/ConnectivityController.java

@@ -1,5 +1,7 @@
 package org.finos.gitproxy.dashboard.controller;
 
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.annotation.Resource;
 import java.net.InetSocketAddress;
 import java.net.Socket;
@@ -56,6 +58,7 @@
  *
  * <p>Requires {@code ROLE_ADMIN}.
  */
+@Tag(name = "Admin", description = "Administrative operations — requires ROLE_ADMIN")
 @Slf4j
 @RestController
 public class ConnectivityController {
@@ -85,6 +88,7 @@ public class ConnectivityController {
      * @param repoPath optional — repo path (e.g. {@code /owner/repo.git}) appended to the provider base URI for the git
      *     probe step; requires {@code provider}
      */
+    @Operation(operationId = "checkConnectivity", summary = "Test outbound connectivity to configured providers")
     @GetMapping("/api/admin/connectivity")
     public Map<String, Object> check(
             @RequestParam(name = "provider", required = false) String providerName,