feat(doc): update the verification and generation of OpenAPI spec fil…

…es (eclipse-edc#2209)

* feat: apply apiGroup configs

* delete embedded swagger UI

* bring back old and outdated Swagger UI

* updated api specs

* create-update logic for API doc

.github/workflows/apidoc.yaml

@@ -0,0 +1,93 @@
+name: Verify and Publish OpenAPI Specs
+
+on:
+  push:
+  pull_request:
+    branches: [ main ]
+    paths-ignore:
+      - '**.md'
+      - 'docs/**'
+      - 'CODEOWNERS'
+      - 'LICENSE'
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  Verify-OpenAPI-Definitions:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: true
+      matrix:
+        apiGroup: [ 'management-api', 'control-api' ]
+    env:
+      rootDir: resources/openapi/yaml/${{ matrix.apiGroup }}
+    steps:
+      - uses: actions/checkout@v3
+      - uses: ./.github/actions/setup-build
+
+      - name: Save previous OpenAPI definition
+        run: |
+          mkdir -p git-sorted/${{ matrix.apiGroup }}
+          files=($(ls $rootDir)) 
+          for file in ${files[@]}; do
+            yq -P 'sort_keys(..)' $rootDir/$file > git-sorted/${{ matrix.apiGroup }}/$file
+          done
+
+      - name: Generate OpenAPI definitions from code
+        run: |
+          export
+          ./gradlew resolve
+
+      # Can be used (and yq tasks removed) when https://github.com/kpramesh2212/openapi-merger-plugin/pull/11/files is merged
+      #- name: Check OpenAPI definitions match code
+      #  run: git diff --exit-code
+
+      - name: Check OpenAPI definitions match code
+        run: |
+          mkdir -p git-regen/${{ matrix.apiGroup }}
+          files=($(ls resources/openapi/yaml/${{ matrix.apiGroup}})) 
+
+          for file in ${files[@]}; do
+            yq -P 'sort_keys(..)' $rootDir/$file > git-regen/${{ matrix.apiGroup }}/$file
+          done
+
+          diff -r git-sorted git-regen
+
+  Publish-To-SwaggerHub:
+    # do NOT run on forks. The Org ("edc") is unique all across SwaggerHub
+    if: github.repository == 'eclipse-edc/Connector' && github.event_name != 'pull_request'
+    runs-on: ubuntu-latest
+    needs: [ Verify-OpenAPI-Definitions ]
+    strategy:
+      matrix:
+        apiGroup: [ 'management-api', 'control-api' ]
+    env:
+      rootDir: resources/openapi/yaml/${{ matrix.apiGroup }}
+      SWAGGERHUB_API_KEY: ${{ secrets.SWAGGERHUB_TOKEN }}
+      SWAGGERHUB_USER: ${{ secrets.SWAGGERHUB_USER }}
+    steps:
+      - uses: actions/checkout@v3
+      - uses: ./.github/actions/setup-build
+      - uses: actions/setup-node@v3
+
+      # merge together all api groups
+      - name: Generate API Specs
+        run: |
+          ./gradlew -PapiTitle="${{ matrix.apiGroup }}" -PapiDescription="REST API documentation for the ${{ matrix.apiGroup }}" :mergeApiSpec --input=${{ env.rootDir }} --output=${{ matrix.apiGroup }}.yaml
+
+      # install swaggerhub CLI
+      - name: Install SwaggerHub CLI
+        run: npm i -g swaggerhub-cli
+
+      # create API, will fail if exists
+      - name: Create API
+        continue-on-error: true
+        run: |
+          swaggerhub api:create ${{ env.SWAGGERHUB_USER }}/${{ matrix.apiGroup}} -f ${{ matrix.apiGroup }}.yaml --visibility=public --published=unpublish
+
+      # Post the API to SwaggerHub as "unpublished", because published APIs cannot be overwritten
+      - name: Publish API Specs to SwaggerHub
+        run: |
+          swaggerhub api:update ${{ env.SWAGGERHUB_USER }}/${{ matrix.apiGroup}} -f ${{ matrix.apiGroup }}.yaml --visibility=public --published=unpublish

.github/workflows/verify.yaml

@@ -45,30 +45,6 @@ jobs:
       - name: Dependency analysis report
         run: cat build/reports/dependency-analysis/build-health-report.txt
 
-  OpenAPI-Definitions:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v3
-      - uses: ./.github/actions/setup-build
-
-      - name: Save previous OpenAPI definition
-        run: yq -P 'sort_keys(..)' resources/openapi/openapi.yaml > openapi-git-sorted.yaml
-
-      - name: Generate OpenAPI definitions from code
-        run: |
-          ./gradlew resolve
-          ./gradlew mergeOpenApiFiles
-
-      # Can be used (and yq tasks removed) when https://github.com/kpramesh2212/openapi-merger-plugin/pull/11/files is merged
-      #- name: Check OpenAPI definitions match code
-      #  run: git diff --exit-code
-
-      - name: Check OpenAPI definitions match code
-        run: |
-          yq -P 'sort_keys(..)' resources/openapi/openapi.yaml > openapi-ci-sorted.yaml
-          diff openapi-git-sorted.yaml openapi-ci-sorted.yaml
-
-
   Unit-Tests:
     runs-on: ubuntu-latest
     env:

build.gradle.kts

@@ -15,8 +15,6 @@
 
 plugins {
     `java-library`
-    // todo: remove once https://github.com/eclipse-edc/Connector/issues/2191 is complete
-    id("org.hidetake.swagger.generator") version "2.19.2"
 }
 
 val javaVersion: String by project
@@ -34,16 +32,15 @@ if (actualVersion == "unspecified") {
 }
 
 buildscript {
+    repositories {
+        mavenLocal()
+    }
     dependencies {
         val edcGradlePluginsVersion: String by project
         classpath("org.eclipse.edc.edc-build:org.eclipse.edc.edc-build.gradle.plugin:${edcGradlePluginsVersion}")
     }
 }
 
-dependencies {
-    "swaggerUI"("org.webjars:swagger-ui:4.15.5")
-}
-
 allprojects {
     apply(plugin = "${groupId}.edc-build")
 
@@ -68,8 +65,9 @@ allprojects {
             scmUrl.set(edcScmUrl)
         }
         swagger {
-            title.set("EDC REST API")
-            description = "EDC REST APIs - merged by OpenApiMerger"
+            title.set((project.findProperty("apiTitle") ?: "EDC REST API") as String)
+            description =
+                (project.findProperty("apiDescription") ?: "EDC REST APIs - merged by OpenApiMerger") as String
             outputFilename.set(project.name)
             outputDirectory.set(file("${rootProject.projectDir.path}/resources/openapi/yaml"))
         }
@@ -100,15 +98,4 @@ if (project.hasProperty("dependency.analysis")) {
     configure<org.eclipse.edc.gradle.DependencyRulesPluginExtension> {
         severity.set(project.property("dependency.analysis").toString())
     }
-}
-
-// todo: remove once https://github.com/eclipse-edc/Connector/issues/2191 is complete
-swaggerSources {
-    create("edc").apply {
-        setInputFile(file("./resources/openapi/openapi.yaml"))
-        ui(closureOf<org.hidetake.gradle.swagger.generator.GenerateSwaggerUI> {
-            outputDir = file("docs/swaggerui")
-            wipeOutputDir = true
-        })
-    }
-}
+}

core/control-plane/control-plane-api/build.gradle.kts

@@ -37,6 +37,13 @@ dependencies {
     testImplementation(libs.awaitility)
 }
 
+edcBuild {
+    swagger {
+        apiGroup.set("control-api")
+    }
+}
+
+
 publishing {
     publications {
         create<MavenPublication>(project.name) {

docs/developer/decision-records/2022-11-09-api-refactoring/renaming.md

@@ -12,7 +12,8 @@ This context will expose the controllers defined by the following modules:
 - `data-management-api`
 - `data-plane-selector`
 - `federated-catalog`
-- `http-provisioner`.
+- `http-provisioner`
+- `observability-api`
 
 Network context: intra-organization
 

extensions/common/api/api-observability/build.gradle.kts

@@ -28,6 +28,12 @@ dependencies {
     testImplementation(project(":core:common:junit"))
 }
 
+edcBuild {
+    swagger {
+        apiGroup.set("management-api")
+    }
+}
+
 publishing {
     publications {
         create<MavenPublication>(project.name) {

extensions/common/api/management-api-configuration/build.gradle.kts

@@ -23,6 +23,12 @@ dependencies {
     testImplementation(project(":core:common:junit"))
 }
 
+edcBuild {
+    swagger {
+        apiGroup.set("management-api")
+    }
+}
+
 publishing {
     publications {
         create<MavenPublication>(project.name) {

extensions/control-plane/api/management-api/asset-api/build.gradle.kts

@@ -32,6 +32,12 @@ dependencies {
     testImplementation(libs.awaitility)
 }
 
+edcBuild {
+    swagger {
+        apiGroup.set("management-api")
+    }
+}
+
 publishing {
     publications {
         create<MavenPublication>(project.name) {

extensions/control-plane/api/management-api/catalog-api/build.gradle.kts

@@ -32,6 +32,12 @@ dependencies {
     testImplementation(libs.restAssured)
 }
 
+edcBuild {
+    swagger {
+        apiGroup.set("management-api")
+    }
+}
+
 publishing {
     publications {
         create<MavenPublication>(project.name) {

extensions/control-plane/api/management-api/contract-agreement-api/build.gradle.kts

@@ -32,6 +32,12 @@ dependencies {
     testImplementation(libs.restAssured)
 }
 
+edcBuild {
+    swagger {
+        apiGroup.set("management-api")
+    }
+}
+
 publishing {
     publications {
         create<MavenPublication>(project.name) {

extensions/control-plane/api/management-api/contract-definition-api/build.gradle.kts

@@ -32,6 +32,12 @@ dependencies {
     testImplementation(libs.awaitility)
 }
 
+edcBuild {
+    swagger {
+        apiGroup.set("management-api")
+    }
+}
+
 publishing {
     publications {
         create<MavenPublication>(project.name) {

extensions/control-plane/api/management-api/contract-negotiation-api/build.gradle.kts

@@ -32,6 +32,12 @@ dependencies {
     testImplementation(libs.awaitility)
 }
 
+edcBuild {
+    swagger {
+        apiGroup.set("management-api")
+    }
+}
+
 publishing {
     publications {
         create<MavenPublication>(project.name) {

extensions/control-plane/api/management-api/policy-definition-api/build.gradle.kts

@@ -38,6 +38,12 @@ dependencies {
     testImplementation(libs.restAssured)
 }
 
+edcBuild {
+    swagger {
+        apiGroup.set("management-api")
+    }
+}
+
 publishing {
     publications {
         create<MavenPublication>(project.name) {

extensions/control-plane/api/management-api/transfer-process-api/build.gradle.kts

@@ -34,6 +34,12 @@ dependencies {
     testImplementation(libs.awaitility)
 }
 
+edcBuild {
+    swagger {
+        apiGroup.set("control-api")
+    }
+}
+
 publishing {
     publications {
         create<MavenPublication>(project.name) {

extensions/control-plane/provision/provision-http/build.gradle.kts

@@ -35,6 +35,13 @@ dependencies {
     testImplementation(libs.awaitility)
 }
 
+edcBuild {
+    swagger {
+        apiGroup.set("management-api")
+    }
+}
+
+
 publishing {
     publications {
         create<MavenPublication>(project.name) {

extensions/control-plane/transfer/transfer-data-plane/build.gradle.kts

@@ -41,6 +41,13 @@ dependencies {
     testImplementation(libs.jersey.multipart)
 }
 
+edcBuild {
+    swagger {
+        apiGroup.set("control-api")
+    }
+}
+
+
 publishing {
     publications {
         create<MavenPublication>(project.name) {

extensions/data-plane-selector/data-plane-selector-api/build.gradle.kts

@@ -30,6 +30,13 @@ dependencies {
     testImplementation(project(":core:common:junit"))
 }
 
+edcBuild {
+    swagger {
+        apiGroup.set("management-api")
+    }
+}
+
+
 publishing {
     publications {
         create<MavenPublication>(project.name) {

extensions/data-plane/data-plane-api/build.gradle.kts

@@ -35,6 +35,11 @@ dependencies {
     testImplementation(libs.mockserver.netty)
     testImplementation(libs.mockserver.client)
 }
+edcBuild {
+    swagger {
+        apiGroup.set("control-api")
+    }
+}
 
 publishing {
     publications {