[
https://issues.apache.org/jira/browse/FINERACT-2501?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Edward Kang updated FINERACT-2501:
----------------------------------
Description:
*Background*
While working on the Cucumber testing initiative, I began implementing a test
core for savings products. During this work, I discovered a potential stability
issue with how our auto-generated Feign client method names are assigned.
*The Problem*
# Fineract uses Swagger/OpenAPI to auto-generate Feign client methods from our
endpoints. Since many endpoints share the same method name (e.g.,
retrieveAll()), Swagger appends a deduplication number to create unique
operationIds. For example, retrieveAll35() for
SavingsProductsApiResource.retrieveAll().
# These deduplication numbers are unstable. When a new endpoint with a
duplicate name is added, the numbers can shift. In my testing, after adding a
new dummy retrieveAll() endpoint, retrieveAll35() no longer pointed to
SavingsProductsApiResource. It actually shifted to retrieveAll36().
# Since we hardcode these deduplicated method names in our Cucumber tests, any
shift will silently call the wrong API, breaking tests.
*Evidence*
I confirmed this by adding a dummy retrieveAll() endpoint. The SavingsProducts
reference shifted from retrieveAll35() to retrieveAll36(), proving new
endpoints get inserted in the middle of the deduplication order.
The recently added loan-originator endpoint's retrieveAll() was assigned
retrieveAll28(), even though retrieveAll1() through retrieveAll40() already
exist confirming mid-list insertion.
Here are some pictures on what happened to the loan-originator endpoint when I
added my dummy retrieveAll() endpoint.
!image-2026-02-23-10-02-00-868.png!
New Build without new endpoint.
!Screenshot 2026-02-23 at 10.04.14 AM.png!
*Resources*
This seems to be a known problem in the Swagger/OpenAPI ecosystem:
- https://github.com/springdoc/springdoc-openapi/issues/2481
*Proposed Fix*
Add explicit operationId values to the @Operation annotations on each endpoint
in our ApiResource classes. This gives us stable, controllable Feign method
names without breaking any core functionality. We just need to change the
method names to match these operationIds. This is to fix the issue of allowing
our HTTP clients to use stable method names from now on.
Relevent for Cucumber testing since Feign client is going to be heavily used
there.
was:
I noticed that we use a Swagger and OpenApi generator for endpoint access with
Feign client, which creates methods that we can call instead of having to
construct endpoints, JSON, etc. ourselves. While using this, I noticed that
simply calling the method names in SavingsProductsApiResource doesn’t work. It
seems we must call the methodName + deduplication number that is assigned by
Swagger (ie. the deduplicated operationId). So far, this is expected behavior.
However, after some investigation, I think this might be an issue down the line
as we build out more tests in Cucumber. This is because when new endpoints are
added with the same method name, they can actually reorder the deduplication
numbers in operationId, causing our Feign client calls to break. Since we are
hardcoding these method names into our tests, this can create issues where
tests need to be rewritten every time a new endpoint is added.
For example, in my tests, when a new retrieveAll() endpoint is added,
retrieveAll35() can shift from referencing the savingsproductsApiResource to
some other ExampleApiResource.
Below I add a new dummy endpoint, you can see the deduplication number of
SavingsProductsApiResource’s retrieveAll() goes from retrieveAll35() to
retrieveAll36(), meaning the new endpoint is inserted in the middle somewhere.
It is also telling that the recent loan-originators endpoint added a
retrieveAll, but it got set as retrieveAll28. This means it got inserted in the
middle since retrieveAll1 and retrieveAll40 exist.
I linked a picture of loan-originator's retrieve all. It shows dedupe number
29. In your build, without my added endpoint, you should look in fineract.yaml
and find that it is retrieveAll_28. Without my new dummy endpoint, a rebuild
sets it back to retrieveAll_28 to confirm this.
!image-2026-02-23-10-02-00-868.png!
New Build without new endpoint.
!Screenshot 2026-02-23 at 10.04.14 AM.png!
I am proposing adding operationId to @Operation in each ApiResource, along with
a refactor of deduplicated method names on currently implemented Feign client
calls to fix this issue. This would not affect the rest of the codebase, but
fix the issue of allowing our HTTP clients to use stable method names from now
on.
> Add operationIds and refactor feign methods to fix unstable deduplication
> numbers generated by swagger
> ------------------------------------------------------------------------------------------------------
>
> Key: FINERACT-2501
> URL: https://issues.apache.org/jira/browse/FINERACT-2501
> Project: Apache Fineract
> Issue Type: Bug
> Reporter: Edward Kang
> Assignee: Edward Kang
> Priority: Major
> Attachments: Screenshot 2026-02-23 at 10.04.14 AM.png,
> image-2026-02-23-10-02-00-868.png
>
>
> *Background*
> While working on the Cucumber testing initiative, I began implementing a test
> core for savings products. During this work, I discovered a potential
> stability issue with how our auto-generated Feign client method names are
> assigned.
> *The Problem*
> # Fineract uses Swagger/OpenAPI to auto-generate Feign client methods from
> our endpoints. Since many endpoints share the same method name (e.g.,
> retrieveAll()), Swagger appends a deduplication number to create unique
> operationIds. For example, retrieveAll35() for
> SavingsProductsApiResource.retrieveAll().
> # These deduplication numbers are unstable. When a new endpoint with a
> duplicate name is added, the numbers can shift. In my testing, after adding a
> new dummy retrieveAll() endpoint, retrieveAll35() no longer pointed to
> SavingsProductsApiResource. It actually shifted to retrieveAll36().
> # Since we hardcode these deduplicated method names in our Cucumber tests,
> any shift will silently call the wrong API, breaking tests.
> *Evidence*
> I confirmed this by adding a dummy retrieveAll() endpoint. The
> SavingsProducts reference shifted from retrieveAll35() to retrieveAll36(),
> proving new endpoints get inserted in the middle of the deduplication order.
> The recently added loan-originator endpoint's retrieveAll() was assigned
> retrieveAll28(), even though retrieveAll1() through retrieveAll40() already
> exist confirming mid-list insertion.
> Here are some pictures on what happened to the loan-originator endpoint when
> I added my dummy retrieveAll() endpoint.
> !image-2026-02-23-10-02-00-868.png!
> New Build without new endpoint.
> !Screenshot 2026-02-23 at 10.04.14 AM.png!
> *Resources*
> This seems to be a known problem in the Swagger/OpenAPI ecosystem:
> - https://github.com/springdoc/springdoc-openapi/issues/2481
> *Proposed Fix*
> Add explicit operationId values to the @Operation annotations on each
> endpoint in our ApiResource classes. This gives us stable, controllable Feign
> method names without breaking any core functionality. We just need to change
> the method names to match these operationIds. This is to fix the issue of
> allowing our HTTP clients to use stable method names from now on.
> Relevent for Cucumber testing since Feign client is going to be heavily used
> there.
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
