API Schema Enrichment & Documentation Audit

API Schema Enrichment

Every route in the SpeyBooks API now carries production-grade OpenAPI schema metadata — params, body, querystring, and response codes — so the documentation site renders complete, accurate reference pages instead of placeholder defaults.

Route Schema Enrichment

• 195 routes audited across 36 files — systematic pass ensuring every endpoint declares its params, body schema, response codes, and descriptions aligned with the handler behaviour.
• Response schema synthesis — the OpenAPI generator now infers schema.properties from sibling example bodies, eliminating the “Default Response” placeholder on 150+ endpoints.
• Params schemas added — routes with URL parameters (:id, :accountId, :key) now declare typed params schemas so the docs site renders parameter descriptions and types.
• Body schemas added — POST and PATCH routes that accept request bodies now have inline OpenAPI schemas with field types, enums, constraints, and descriptions matching their Zod validators.
• Error response codes declared — 400, 404, 409, and 422 responses added where handlers return them but schemas didn’t declare them. The docs site now shows the full error surface for each endpoint.

Files Enriched

• Core resources — invoices, transactions, categorisation-rules, quotes
• TMADD pipeline — invoice-imports, bill-imports, contact-imports, opening-balances, migrations
• Integration — api-keys, webhook-endpoints
• Admin — admin, admin-additions

Audit Tooling

• Route audit script — Python script scanning all 36 route files and 37 sibling doc files, detecting missing schemas, undeclared response codes, and sibling gaps. Produces a prioritised issue queue.
• Variable-reference detection — the script now recognises params: sharedSchema variable references, not just inline params: { ... } blocks, eliminating false positives on well-structured files.
• Zod fallback detection — routes using .parse(request.body) in the handler are recognised as having body validation, even without an inline schema block.
• Action endpoint heuristic — bodyless POST routes (confirm, void, validate, execute) that have params and response schemas but never reference request.body are correctly identified as action endpoints rather than flagged as missing body schemas.

Results

• 175 of 195 routes fully compliant — up from 19 at the start of the session.
• 21 remaining flags — all either intentional design choices (action endpoints using 422 instead of 400) or non-paginated list endpoints.
• Zero sibling gaps — every route file has a matching .doc.ts with descriptions, curl examples, and response examples.