feat: add GET /docs endpoint serving Swagger UI for the OpenAPI spec

[Copilot]

GET /api returns raw YAML, which browsers download rather than render. This adds a GET /docs endpoint that serves a minimal HTML page embedding Swagger UI (CDN-loaded, pinned to swagger-ui-dist@5), pointed at the existing /api spec via a relative ./api URL — no host hardcoding, works across all API Gateway stages and custom domains.

Overview

src/handlers/handler_api.py — new get_docs() method:

def get_docs(self) -> dict[str, Any]:
    """Return a Swagger UI HTML page for browsing the API spec."""
    ...
    return {"statusCode": 200, "headers": {"Content-Type": "text/html"}, "body": html}

The HTML body loads swagger-ui-dist@5 from jsDelivr and initialises SwaggerUIBundle({ url: "./api", dom_id: "#swagger-ui" }).

src/event_gate_lambda.py — registered in ROUTE_MAP:

"/docs": lambda _: handler_api.get_docs(),

api.yaml — /docs path documented with security: [] and 200 text/html response.

Release Notes

• Added GET /docs endpoint: returns an interactive Swagger UI page rendered against the existing /api OpenAPI spec

Deployment

⚠️ Deployment note: API Gateway must have a /docs resource (or an existing {proxy+} catch-all) routed to the EventGate Lambda. Without this, /docs will 404 at the gateway even after deploying this change. This will be done here: https://github.com/absa-group/cps-eventbus-gateway/pull/124

Closes: #191

[tmikula-dev]

Like this approach! Thanks for this PR.

[oto-macenauer-absa]

Works, but I'd add replacement of cdn.jsdelivr.net with bundles created during the docker build (inside Dockerfile) in future.

I have created an issue for the consideration: #197

[lsulak]

Works, but I'd add replacement of cdn.jsdelivr.net with bundles created during the docker build (inside Dockerfile) in future.

I have created an issue for the consideration: #197

ok, thanks! I'll adjust it right away, outside of this PR since I've got approvals & I want to keep things small