Description
The original documentation for Fineract is at https://github.com/apache/fineract/blob/develop/api-docs/apiLive.htm. This documentation was handcrafted to meet the following goals
- Provide a detailed overview of the API design and common options (under "Overview" section of the top Navbar at https://demo.openmf.org/api-docs/apiLive.htm)
- Help consumers to easily visualize related API's to quickly determine the scope of functionality supported by the system ( Ex: links to all loan related API's consolidated under the "Loan" section of the navbar)
- For each entity in the system, provide a meaningful description of what the entity represents in the real world (Ex: https://demo.openmf.org/api-docs/apiLive.htm#glaccounts )
- For common fields associated with an entity, provide a meaningful description of what they represent and how they are to be used (Ex: https://demo.openmf.org/api-docs/apiLive.htm#loans , see the description and detailed explanation of fields like transactionProcessingStrategyId )
- Provide a detailed overview of the functionality supported by each API call (especially when their usage is not obvious, see the detailed documentation for Batch API's at https://demo.openmf.org/api-docs/apiLive.htm#batch_api )
- Provide examples of sample requests and responses for each API call
However, this documentation suffered a major drawback, i.e all of it was handwritten and was difficult for new committers to add to and maintain. It was also preferable that users be allowed to try out all API's from the documentation itself, which wasn't an option.
The newly added Swagger documentation aims to address these concerns. The current status of the same and the work needed to meet the goals of the original documentation is described below
Goal 1
The swagger docs rely on the existing API docs through hyperlinks for the entire overview section. To make the swagger docs the single source of truth for API documentation, the existing docs need to be deprecated. For doing the same, this entire section needs to be copied over to the swagger UI (and well formatted) and all references to the older docs removed. **
Goal 2
All API's are currently listed in a random order and someone new to the system cannot comprehend relationships between them. The home page needs to be improved with either a sidebar or a navbar (similar to the one in the existing documentation) which groups together related API's and provides hyperlinks to their swagger documentation
Goal 3
While entity descriptions seem to be present in the codebase (Ex: https://github.com/apache/fineract/blob/201cbf82f67f7a623b8c38bf9465f4af79791c20/fineract-provider/src/main/java/org/apache/fineract/portfolio/savings/api/SavingsAccountsApiResource.java#L76), they aren't reflected in the generated documentation. This is likely because the description field is deprecated, see discussion at https://github.com/swagger-api/swagger-core/issues/1476.
It would be nice if this description was well formatted too.
Goal 4
Taking https://demo.openmf.org/api-docs/apiLive.htm#loans as an example, the details and descriptions of fields like "transactionProcessingStrategyId" are not carried over. Without this information, an API consumer would not understand what each of these (non-obvious) fields mean and how they are to be used.
Goal 5
The amount of information present for an API like https://demo.openmf.org/api-docs/apiLive.htm#batch_api is significantly more than that of the equivalent API in Swagger (detailed description, possible errors, command strategies supported etc). We would need to go through each API to ensure that all information is migrated.
Here's a screenshot of another commonly used API for updating loan statuses from swagger docs.
Issues here
- Details of actual commands supported (approve, reject) are missing
- Lack of formatting makes it hard to read
Goal 6
At first glance, it looks like the swagger documentation does a good job here. We probably need a round of QA to certify the same
Attachments
Attachments
Issue Links
- is duplicated by
-
FINERACT-422 REST API "live" documentation (Using OpenAPI/Swagger)
-
- Resolved
-
-
-
- Resolved
-
- is related to
-
FINERACT-1100 Swagger CodeGen WARN i.s.c.v.g.java.AbstractJavaCodegen - New (reserved word) cannot be used as model name. Renamed to ModelNew
-
- Resolved
-
-
-
- Resolved
-
-
-
- Resolved
-
-
FINERACT-1102 Swagger Codegen Client JAR should be available on a Maven repo
-
- In Progress
-
-
-
- Resolved
-
-
-
- Resolved
-
-
-
- Resolved
-
-
-
- Closed
-
-
-
- Closed
-
-
-
- Closed
-
-
-
- Closed
-
- links to
