Add automated OpenAPI specification for mgmt_api (drasi-project#309)

Add automated OpenAPI specification for mgmt_api

This commit introduces a robust, automated system for generating and maintaining an OpenAPI 3.0 specification for the management API.
This provides a version-controlled API contract that is always in sync with the implementation.

The previous macro-based routes have been refactored into explicit Actix handlers.
Generic DTOs in the API layer were replaced with concrete structs (e.g., SourceDto)
  to resolve a utoipa limitation and produce a valid spec.

Key changes include:
- Integrated the utoipa crate to generate the spec from Rust code.
- Aligns the mgmt_api crate version to 1.0.0 to match the /v1 API path.
- Adds a pre-commit hook to enforce local spec updates.
- Adds CI jobs to verify spec sync and detect breaking changes.
    - verify-openapi-spec: Fails the build if the committed spec is out of date.
    - detect-breaking-api-changes: Uses openapi-diff to prevent merging backward-incompatible changes.

Signed-off-by: Aman Singh <aman.singh.original@gmail.com>

Author: amansinghoriginal

.githooks/pre-commit

@@ -7,6 +7,22 @@ case ":${PATH}:" in
         ;;
 esac
 
+echo "Running pre-commit hook: Checking for API spec changes..."
+
+# Generate the latest spec based on the current code
+make -C control-planes/mgmt_api openapi-generate
+
+# Check if the generated spec file has unstaged changes
+if ! git diff --quiet HEAD control-planes/mgmt_api/openapi.yaml; then
+    echo "\nERROR: API specification is out of date."
+    echo "The OpenAPI spec has been regenerated based on your code changes."
+    echo "Please stage the updated file to include it in your commit:"
+    echo "\n    git add control-planes/mgmt_api/openapi.yaml\n"
+    exit 1
+fi
+
+echo "API spec is up to date."
+
 echo "Running cargo fmt for query container..."
 cargo fmt  --manifest-path ./query-container/Cargo.toml --check
 

.github/workflows/build-test.yml

@@ -33,6 +33,87 @@ permissions:
   packages: write
 
 jobs:
+  verify-openapi-spec:
+    name: Verify OpenAPI Specification
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Install system dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y protobuf-compiler
+
+      - name: Install Rust toolchain
+        uses: actions-rs/toolchain@v1
+        with:
+          toolchain: stable
+          override: true
+
+      - name: Cache Cargo dependencies
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+          key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }}
+
+      - name: Generate OpenAPI Spec
+        run: make -C control-planes/mgmt_api openapi-generate
+
+      - name: Check for diff
+        run: |
+          if ! git diff --quiet HEAD control-planes/mgmt_api/openapi.yaml; then
+            echo "ERROR: The generated OpenAPI specification is out of date."
+            echo "Please run 'make -C control-planes/mgmt_api openapi-generate' and commit the changes."
+            exit 1
+          fi
+          echo "OpenAPI specification is up to date."
+
+  detect-breaking-api-changes:
+    name: Detect Breaking API Changes
+    runs-on: ubuntu-latest
+    # TODO: Enable this job after the initial OpenAPI PR is merged
+    # For now, skip it since there's no spec in main branch to compare against
+    if: false
+    # if: github.base_ref == 'main' && github.event_name == 'pull_request'
+    steps:
+      - name: Checkout PR branch
+        uses: actions/checkout@v4
+
+      - name: Checkout base branch (main)
+        uses: actions/checkout@v4
+        with:
+          ref: main
+          path: main
+
+      - name: Install system dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y protobuf-compiler
+
+      - name: Install Rust toolchain
+        uses: actions-rs/toolchain@v1
+        with:
+          toolchain: stable
+          override: true
+
+      - name: Generate OpenAPI Spec for PR
+        run: make -C control-planes/mgmt_api openapi-generate
+
+      - name: Generate OpenAPI Spec for main branch
+        run: |
+          cd main
+          make -C control-planes/mgmt_api openapi-generate
+
+      - name: Install openapi-diff
+        run: npm install -g openapi-diff
+
+      - name: Run openapi-diff
+        run: |
+          openapi-diff main/control-planes/mgmt_api/openapi.yaml control-planes/mgmt_api/openapi.yaml --fail-on-incompatible
+
   build-images:
     permissions:
       packages: write

control-planes/mgmt_api/.gitignore

@@ -1 +1,4 @@
-/target
+/target
+openapitools.json
+# Allow src/bin for Rust binary sources
+!/src/bin/

control-planes/mgmt_api/Cargo.lock

@@ -1,15 +1,21 @@
 [package]
 name = "mgmt_api"
-version = "0.1.0"
+version = "1.0.0"
 edition = "2021"
 
+[[bin]]
+name = "generate-spec"
+path = "src/bin/generate-spec.rs"
+
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
 
 [dependencies]
 resource_provider_api = { path = "../resource_provider_api" }
 drasi-comms-abstractions = { path = "../../infrastructure/comms-abstractions" }
 drasi-comms-dapr = { path = "../../infrastructure/comms-dapr" }
 dapr = "=0.15.1"
+utoipa = { version = "4", features = ["actix_extras", "chrono", "yaml"] }
+utoipa-swagger-ui = { version = "6", features = ["actix-web"] }
 async-stream = "0.3.5"
 async-trait = "0.1"
 actix = "0.13"

control-planes/mgmt_api/Cargo.toml

@@ -24,7 +24,7 @@ WORKDIR /usr/src/control-planes/mgmt_api
 COPY ./control-planes/mgmt_api/Cargo.toml .
 RUN cargo fetch
 COPY ./control-planes/mgmt_api .
-RUN cargo install --force --path .
+RUN cargo install --force --path . --bin mgmt_api
 
 FROM mcr.microsoft.com/azurelinux/distroless/base:3.0
 COPY --from=builder /usr/local/cargo/bin/mgmt_api /usr/local/bin/mgmt_api