Thanks both — agreed, a versioned (v2) API is the safer path here rather than breaking existing consumers. I'll open a tracking issue covering the five affected resources so this has a concrete home, following the pattern Arnold linked.
Regards, Lukman On Tue, Aug 4, 2026 at 7:27 AM elnafateh <[email protected]> wrote: > 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 >
