What does this PR do?

Fixes Swagger UI silently dropping the Authorization header so "Try it out" requests no longer fail with 401/403.

API v2 endpoints document authentication with @ApiHeader({ name: "Authorization" }). The OpenAPI specification, however, mandates that a header parameter named Authorization be ignored, so Swagger UI renders the input field and accepts a value but never attaches the header to the outgoing request. Users fill in Bearer cal_xxx, hit Execute, and every authenticated call fails even though the UI suggested the token would be sent.

The fix, all contained in apps/api/v2/src/swagger/generate-swagger.ts:

1. Registers a proper bearer security scheme on the OpenAPI document (addBearerAuth), which gives Swagger UI a working Authorize button.
2. Adds applyAuthorizationSecurity(), a post-processing step that, for every operation which declared the (ignored) Authorization header, removes that parameter and attaches the bearer security requirement instead — so Swagger UI actually sends Authorization: Bearer <token>.

Operations that never declared an Authorization header (genuinely public endpoints) are left untouched, and any pre-existing per-operation security is preserved (the requirement is appended, not overwritten). Because the transform runs centrally, no per-controller changes are needed.

• Fixes Swagger UI silently drops Authorization header defined with @ApiHeader #29564

Visual Demo (For contributors especially)

N/A — this changes the generated OpenAPI document / Swagger UI behaviour. The resulting document now contains a components.securitySchemes.Authorization bearer scheme and a security requirement on the affected operations, which is exactly what makes Swagger UI attach the header. This is asserted by the unit tests below.

Mandatory Tasks (DO NOT REMOVE)

• I have self-reviewed the code (A decent size PR without self-review might be rejected).
• I have updated the developer docs if this PR makes changes that would require a documentation change. If N/A, write N/A here and check the checkbox. — N/A
• I confirm automated tests are in place that prove my fix is effective or that my feature works.

How should this be tested?

No environment variables or DB are required for the unit tests — applyAuthorizationSecurity is a pure function over an OpenAPI document.

cd apps/api/v2
yarn jest src/swagger/generate-swagger.spec.ts

Expected: 5 tests pass, covering:

• An operation with an Authorization header → the header parameter is removed and a { Authorization: [] } security requirement is added.
• A public operation (no Authorization header) → left untouched.
• An operation with pre-existing security → the requirement is appended, not overwritten.
• $ref parameters → handled without throwing.
• A document with no paths → returned unchanged.

Manual verification in Swagger UI: open /docs, click Authorize, enter an API key / access token, then Execute any authenticated endpoint and confirm the generated curl now includes -H 'Authorization: Bearer <token>'.

Checklist

• I have read the contributing guide.
• My code follows the style guidelines of this project.
• I have commented my code, particularly in hard-to-understand areas.
• I have checked that my changes generate no new warnings.
• My PR is small (1 source file + 1 test file).