fix: resolve OpenAPI spec issues causing APIM deployment failures

[devin-ai-integration]

Summary

Fixes multiple issues in the upstream OpenAPI specification that cause Azure API Management (APIM) to reject the spec during import via the ApiOps deployment pipeline. Also adds a CI validation workflow so these issues are caught before merge going forward.

Spec fixes:

• customers/customers.yaml: Fixed 4 broken $ref paths on GET /customers/{customerId} — ./shared/standard-responses.yaml → ../shared/standard-responses.yaml (wrong relative path; ./shared/ resolves to customers/shared/ which doesn't exist)
• bookings/bookings.yaml: Uncommented the 200 response on GET /bookings/{bookingId} — APIM requires at least one 2xx response per operation
• bookings/bookings.yaml: Added missing path parameter definitions (bookingId, notificationId) to three notification endpoints (GET /notifications, GET /notifications/{notificationId}, PUT /notifications/{notificationId}) — APIM requires all {template} variables in the path to have corresponding parameter declarations
• main.yaml: Removed empty variables: {} from the first server entry (bundling artifact incompatible with APIM)

New CI workflow (.github/workflows/validate.yaml):
Runs on PRs to master and pushes to master. Bundles the spec with redocly bundle, runs redocly lint (non-blocking due to pre-existing warnings), then runs a Python validation script that checks APIM-specific requirements: no external/broken $refs, all operations have a 2xx response, all path template variables have parameter definitions, no empty server variables objects.

Context: These issues were discovered after the bundled spec was imported into the ApiOps repo and the deployment pipeline failed. Fixes were applied downstream in PRs #693657 and #693914 on the ApiOps repo; this PR fixes the root cause upstream so the issues don't recur on re-bundling.

Review & Testing Checklist for Human

• Verify the 200 response schema for GetBooking — the uncommented $ref points to ../bookings/components/booking-response.yaml (which wraps view-booking.yaml). Confirm this matches the actual API response shape.
• Verify notification path parameters are typed correctly — all three notification endpoints now declare bookingId and notificationId as type: string. Confirm this matches the actual API's parameter types.
• Run docker-compose up and check docs render correctly — open http://localhost:8080 and verify the GetBooking endpoint now shows a 200 response, the notification endpoints show their path parameters, and the GetCustomer endpoint still renders without errors.
• Re-bundle and re-import to APIM — after merging, run redocly bundle main.yaml -o bundled.yaml --force and verify the bundled output can be successfully imported into APIM (or re-run the ApiOps pipeline with updated artifacts).

Notes

• The redocly lint step uses continue-on-error: true because there are ~40+ pre-existing warnings (mostly example format mismatches like date-time examples without the T separator). These are cosmetic and don't affect APIM import, but they would block CI if the lint step were strict. A follow-up could clean those up and remove continue-on-error.
• The APIM compatibility validation step is the hard gate — it will fail the workflow if any of the checked rules are violated.

Link to Devin session: https://app.devin.ai/sessions/c706e71f8d9c4a3d8b5f74e7f0c43709

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment and CI monitoring