[
https://issues.apache.org/jira/browse/FINERACT-2501?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Edward Kang updated FINERACT-2501:
----------------------------------
Labels: gsoc-fineract-evidence (was: )
> 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
> Labels: gsoc-fineract-evidence
> 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)
