Backlog: Add OpenAPI contract generation and drift checks

[kishorjakkula]

Goal

Add automated checks that keep the OpenAPI/API documentation aligned with runtime routes, schemas, and error contracts.

Why

Issues #85 and #91 improve validation and error documentation, but contributors also need a quality gate that catches API documentation drift. Carrier integrations rely on stable and accurate route, request, response, and error contracts.

Expected Scope

• Decide whether OpenAPI should be generated from route/schema metadata, snapshot-tested, or validated by a dedicated spec test.
• Add tests that verify /openapi.json includes expected common schemas and route coverage.
• Include standard response envelopes, pagination metadata, validation errors, authorization errors, idempotency conflicts, and traceId error metadata.
• Document how contributors update API docs when routes or schemas change.
• Update PR guidance if API/schema changes require OpenAPI validation notes.

Acceptance Criteria

• API docs fail tests when important routes, schemas, or standard errors drift.
• OpenAPI examples match actual Express responses.
• Contributors have a clear process for API contract updates.
• The quality gate is fast enough for normal CI.

Suggested Validation

npm run test --workspace=server
npm run build:server

Manually inspect /openapi.json for one or two route groups after changes.