[Backend] OpenAPI Runtime Request & Response Validation Middleware

[blurbeast]

Overview & Background

The FlowFi Express backend uses OpenAPI 3.1 Swagger specifications to document REST endpoints. However, without automated runtime enforcement, manual route controllers can accept invalid query parameters, accept unexpected body formats, or return payloads that diverge from the documented schema.

---

Detailed Problem Statement

• Manual validation logic is duplicated across controllers.
• Undocumented query parameters and edge-case type coercions bypass validation.

---

Technical Specification & Architecture

1. Middleware Integration:
   • Implement an OpenAPI validation middleware in backend/src/middleware/schema-validator.middleware.ts.
   • Bind request path, query, and body validation directly to Zod schemas matching the OpenAPI specification.
2. Strict Error Formatting:
   • Standardize all 400 Bad Request responses to RFC 7807 Problem Details:

     {
       "type": "https://flowfi.org/errors/invalid-parameters",
       "title": "Invalid Request Parameters",
       "status": 400,
       "detail": "Invalid parameter 'duration': must be greater than 0",
       "invalidParams": [{ "name": "duration", "reason": "Expected positive integer" }]
     }

3. Response Validation in Test Environment:
   • In test suite, validate all controller responses against the OpenAPI schema to guarantee zero contract drift.

---

Target Files

• backend/src/middleware/schema-validator.middleware.ts
• backend/src/app.ts
• backend/tests/unit/validation.test.ts

---

Acceptance Criteria

• Requests with invalid headers, query parameters, or body payloads are rejected with standardized 400 responses.
• Eliminates duplicated parameter parsing across controllers.
• Automated test suite verifies schema conformance.

[jchinedu]

let me work on this issue