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
