feat: add API Migration Status page

.github/workflows/migration-status.yml

@@ -0,0 +1,47 @@
+name: Update Migration Status Dashboard
+
+on:
+  schedule:
+    # Run daily at 00:00 UTC
+    - cron: "0 0 * * *"
+  workflow_dispatch:
+  # Allow nethcti-server and nethcti-middleware to trigger this workflow
+  repository_dispatch:
+    types: [migration-status-update]
+
+permissions:
+  contents: write
+
+jobs:
+  generate:
+    name: Generate migration data
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout nethvoice-docs
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          # Use the workflow token for the authenticated push at the end
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Generate migration-data.json
+        run: |
+          python3 scripts/extract-migration-status.py
+
+      - name: Commit and push updated data
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add static/migration-data.json
+          # Only commit and push if the file changed
+          if git diff --staged --quiet; then
+            echo "No changes to migration data, skipping commit."
+          else
+            git commit -m "chore: update migration status data"
+            git push
+          fi

docs/tutorial/api/cti.md

@@ -9,7 +9,7 @@ The CTI API provides programmatic access to the NethVoice CTI (Computer Telephon
 Legacy methods are also documented for reference, but migrating to the new methods is strongly recommended.
 New features and improvements are only available in the new API.
 
-Full API specification is available at: [NethCTI Server full reference](https://documenter.getpostman.com/view/15699632/TzRRC88p#41f9b8cc-bea8-4917-a293-84eaedcaed08)
+Full API specification is available at: [NethCTI Server full reference](https://documenter.getpostman.com/view/15699632/TzRRC88p#41f9b8cc-bea8-4917-a293-84eaedcaed08) · [NethCTI Middleware reference](https://bump.sh/nethesis/doc/nethcti-middleware/)
 
 ---
 
@@ -291,6 +291,8 @@ const socket = io('https://nethcti.example.com', {
 
 ## Migration Guide: Legacy to New Method {#migration-guide-legacy-to-new-method}
 
+For a full overview of which endpoints have already been migrated and which are still proxied to the legacy server, see the [API Migration Status dashboard](/migration-status).
+
 To migrate from the legacy authentication to the new JWT-based method:
 
 1. **Replace login endpoint**: Change from `/webrest/authentication/login` to `/api/login`

docusaurus.config.ts

@@ -204,6 +204,23 @@ const config: Config = {
             },
           ],
         },
+        {
+          title: 'Developers',
+          items: [
+            {
+              label: 'Middleware API reference',
+              href: 'https://bump.sh/nethesis/doc/nethcti-middleware/',
+            },
+            {
+              label: 'CTI Server API reference',
+              href: 'https://documenter.getpostman.com/view/15699632/TzRRC88p',
+            },
+            {
+              label: 'API Migration Status',
+              to: '/migration-status',
+            },
+          ],
+        },
         {
           title: 'More',
           items: [

scripts/README.md

@@ -2,7 +2,76 @@
 
 This directory contains utility scripts for managing the NethVoice documentation.
 
-## Import Scripts
+## Migration Status Dashboard
+
+### Generate migration-data.json
+
+The script fetches `nethcti-server` and `nethcti-middleware` from GitHub (shallow clone)
+and produces `static/migration-data.json`, read by the migration status dashboard page.
+
+Default usage — always fetches the production reference branches (`ns8` for
+`nethcti-server`, `main` for `nethcti-middleware`):
+
+> **Requires Python 3.10 or later.**
+
+```bash
+# run from the nethvoice-docs repo root
+python3 scripts/extract-migration-status.py
+```
+
+To test against a different branch before merging:
+
+```bash
+python3 scripts/extract-migration-status.py \
+  --server-branch my-feature-branch \
+  --middleware-branch my-feature-branch
+```
+
+Only one of the two flags is needed if you want to override a single branch:
+
+```bash
+python3 scripts/extract-migration-status.py --server-branch my-fix
+```
+
+> **Note:** The script always clones directly from GitHub remote — it never reads
+> local repository files. The branches it clones must therefore already be pushed to
+> `origin`. There is nothing to commit or stash locally before running the script.
+
+To force regeneration even when endpoint data has not changed (e.g. to update commit
+SHAs or timestamps for a new deployment):
+
+```bash
+python3 scripts/extract-migration-status.py --force
+```
+
+Output is always written to `static/migration-data.json`. If the generated data is
+identical to the existing file (excluding the `generated_at` timestamp and the `sources`
+section which contains commit SHAs), the file is left unchanged so that CI does not
+produce spurious commits. This means the commit SHAs shown in the dashboard reflect the
+last run that actually changed endpoint data, not necessarily the latest commit.
+
+### Manual endpoint mappings
+
+When a legacy path is replaced by a new path with a different name in the middleware,
+add `@migration-replaces` annotations in `nethcti-middleware/main.go` directly above
+the route definition:
+
+```go
+// @migration-replaces: POST /authentication/old_endpoint
+// @migration-note: Optional explanation of the change.
+api.POST("/new/endpoint", methods.Handler)
+```
+
+- `@migration-replaces` must include the HTTP method and the **legacy** path.
+- Multiple `@migration-replaces` lines can appear before a single route (one per legacy path).
+- `@migration-note` is optional and accepts free-form text.
+- The annotation block may contain blank lines and plain `//` comments between entries, but
+  must not be interrupted by any other code before the route declaration.
+
+The extraction script reads these annotations directly from the cloned middleware source —
+no separate mapping file is needed.
+
+
 
 ### Import a RST Document