[UD] Swagger UI route served under `/dashboard/api/swagger` instead of `/dashboard/swagger`; local development OAuth and stability gaps

[olexii4]

Describe the bug

Three independent problems are bundled here because they all block the same local-development workflow.

---

1. Swagger route prefix conflicts with API namespace

The Swagger UI and its JSON spec are mounted at /dashboard/api/swagger, which places documentation inside the /dashboard/api/ namespace reserved for backend API endpoints. This causes two problems:

• Any route guard, proxy rule, or middleware that blanket-applies to /dashboard/api/** (authentication, CORS, rate-limiting) also applies to the documentation, making the spec unreachable in secured deployments.
• The OpenAPI JSON URL embedded in the Swagger UI resolves incorrectly when accessed through the Che gateway, returning a 404.

Expected route: /dashboard/swagger (documentation separate from API)
Actual route: /dashboard/api/swagger

---

2. Local run on OpenShift uses the dashboard service account token instead of the user's OAuth token

When running locally against a CRC/OpenShift cluster, local-run.sh forwards the dashboard service account token as CLUSTER_ACCESS_TOKEN. This is the wrong identity: the service account token belongs to the che-dashboard pod, not to the developer. Workspace API calls that require the user's own RBAC permissions (e.g. creating a DevWorkspace in the user's namespace) succeed only by accident — because the service account happens to have broad cluster rights — and break on tighter clusters where it does not.

The correct token is the developer's own OAuth token, obtainable via oc whoami -t. That token is already present on the developer's machine but was never wired into the local-run flow. As a result:

• Workspace operations run under the service account identity, not the user's, masking permission errors that would appear in production.
• On clusters where oc is not available or the developer is not logged in, the service account token is unavailable too, so all workspace API calls fail with 401 and no clear error is surfaced.
• The Minikube/dex code path authenticates the developer through a browser login window; OpenShift has no equivalent, creating inconsistent UX between the two local-run modes.

---

3. Local-run pod resolution matches Terminating pods during rollouts

local-run.sh resolves the dashboard pod by label selector without filtering on phase. During any image rollout there are two pods — one Running, one Terminating — and the script can pick the terminating one, causing the port-forward to fail immediately.

The dex configMap patch also uses replace mode; if the Che operator detects the change and overwrites it, the local configMap diverges silently and OAuth breaks.

---

Steps to reproduce

Swagger route (issue 1)

1. Deploy Eclipse Che.
2. Open {che-url}/dashboard/api/swagger — the Swagger UI loads.
3. Inspect the "Servers" dropdown in the Swagger UI — the base URL shown includes /api/swagger.
4. From a terminal: curl {che-url}/dashboard/api/swagger/json — observe it returns the spec.
5. Open {che-url}/dashboard/swagger — 404.

Local run on OpenShift (issue 2)

1. Clone che-dashboard, install dependencies.
2. Connect oc to a CRC cluster.
3. Run yarn start -c (local-run mode against OpenShift inside Eclipse-che).
4. Open http://localhost:8080/dashboard/ — dashboard loads without any browser login prompt.
5. Try to create or start a workspace — observe the request succeeds only as long as the oc whoami -t token is valid; rotate the token and the session breaks with no recovery path.

Terminating pod resolution (issue 3)

1. Start yarn start with a running port-forward.
2. Trigger a pod rollout (e.g., patch the dashboard image).
3. Observe the port-forward drops and the script does not reconnect to the new Running pod.

---

Expected behavior

1. Swagger UI and spec are served at /dashboard/swagger and /dashboard/swagger/json. The /dashboard/api/ namespace contains only backend API endpoints.
2. When running locally against an OpenShift cluster, the dashboard opens a browser OAuth window (same UX as Minikube/dex) and exchanges a short-lived token. oc whoami -t is used only as a fallback for CLUSTER_ACCESS_TOKEN when the OAuth flow is unavailable (yarn start -c).
3. Pod resolution in local-run.sh filters to Running phase only, ensuring port-forward always targets the live pod.

---

Che version

next (development version)

Runtime

OpenShift (CRC for local development)

Installation method

chectl/next; local dev with yarn start

Environment

macOS