Hi all,
While adding typed OpenAPI responses for GET /v1/audits (FINERACT-2165), a reviewer flagged that the schema I'd added was inaccurate: the endpoint returns a plain JSON array when paged is false or omitted, and a {totalFilteredRecords, pageItems} wrapper when paged=true. A single @ApiResponse schema can only describe one of those shapes, so whichever one we document, the spec misrepresents the other.
This isn't unique to Audits. GroupsApiResource, CentersApiResource, and FixedDepositAccountsApiResource all have the identical pattern — a boolean paged param that silently switches the response between a raw array and a page wrapper — and all three currently document only the wrapper shape, meaning their generated clients are already inaccurate for unpaged calls. This looks like it was a deliberate design choice at some point (likely to preserve backward compatibility for older non-paginated consumers), but it's now actively blocking correct typed-client generation for any of these five resources.
For contrast, ClientsApiResource, LoansApiResource, and SavingsAccountsApiResource don't have this problem at all — they support offset/limit but always return the single, unambiguous page-wrapper shape, with no boolean toggle to a raw array. That's arguably how this should have been designed everywhere from the start.
I'd like the list's input on how to resolve this, since it affects multiple resources and the fix scope depends on how much we're willing to change.
Happy to pick this up once there's consensus, and to apply whatever we land on consistently across all affected resources.
Thanks,
Lukman
