fix(api): align OpenAPI spec with engine routes and models

Artyom Kartasovrequested to merge
fix/openapi-spec-inconsistencies into master

The OpenAPI spec had drifted from the engine: /admin/ws-auth was documented as POST with a summary copied from test-db-source, 7 routed operations were missing, and several schemas did not match what the handlers write.

Changes in engine/api/swagger-spec/dblab_openapi.yaml:

  • /admin/ws-auth: GET, as routed; own summary and operationId; 401 -> Error; 500 documented; dropped the 400 it never returns. Same method fix in dblab_server_swagger.yaml.
  • Added the routed but undocumented operations: GET /snapshot/{id}, POST /snapshot/clone, POST /admin/probe-source, GET /admin/billing-status, POST /admin/activate, POST /healthz, GET /instance/logs (WebSocket). Router and spec now list the same 39 operations.
  • Response schemas: 401 bodies that referenced Instance; test-db-source returns TestConnectionResponse, not an empty body; config.yaml returns a YAML string, not Config; POST /snapshot returns CreatedSnapshot; SnapshotDetails.child/root are arrays; Retrieving.alerts is an object keyed by alert type.
  • Types: Engine.billingActive is boolean; compressRatio, expectedCloningTime, cloningTime and the observation durations are number; replicationLag is integer.
  • Fields: added Clone.branch/revision, Database.dbName/ownerUser, Snapshot.clones/branch/message, the missing Branch and SnapshotDetails fields, CreateClone.extra_conf; removed Clone.name, Error.detail/hint and the unused SummaryObservationRequest.
  • Status codes and parameters: 401 on the 12 operations that lacked it, the 400/404 responses handlers return, no body on DELETE /clone/{id} and reset, dataset query on GET /snapshots, integer session_id, artifact_type enum, required fields, an operationId on every operation.
  • */* -> application/json.

Redocly reports the spec as valid. Examples that violate their schema went from 42 to 2; both are activity: null, which Redocly does not accept through nullable + allOf.

The two commented-out 404 TODO blocks stay as they are: the engine returns 500 there. That and four other handler bugs found during the audit are tracked in #782 (closed).

Merge request reports