[jira] [Resolved] (FINERACT-2501) Add operationIds and refactor feign methods to fix unstable deduplication numbers generated by swagger

["Adam Saghy (Jira)" <ji...@apache.org>]

     [ https://issues.apache.org/jira/browse/FINERACT-2501?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]

Adam Saghy resolved FINERACT-2501.
----------------------------------
    Fix Version/s: 1.15.0
       Resolution: Fixed

> 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
>             Fix For: 1.15.0
>
>         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)