[
https://issues.apache.org/jira/browse/FINERACT-733?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17018925#comment-17018925
]
Michael Vorburger commented on FINERACT-733:
--------------------------------------------
https://github.com/apache/fineract/pull/629 with [~kangbreder] first
contribution was just finally merged as
https://github.com/apache/fineract/pull/695. As far as I understand, that PR
does not implement everything that was described above. I think that's
perfectly fine, and would suggest to incrementally improve it and raise new
much smaller PRs for specific new goals. I've just created a few additional
sub-tasks on this JIRA proposing some such incremental goals.
> Swagger Documentation for Fineract API's
> ----------------------------------------
>
> Key: FINERACT-733
> URL: https://issues.apache.org/jira/browse/FINERACT-733
> Project: Apache Fineract
> Issue Type: Improvement
> Reporter: Vishwas Babu A J
> Priority: Major
> Labels: gsoc2019
> Fix For: 1.5.0
>
> Attachments: Screen Shot 2019-03-17 at 3.59.23 AM.png
>
> Time Spent: 10m
> Remaining Estimate: 0h
>
> 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|https://demo.openmf.org/api-docs/apiLive.htm#loans])
> # 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.
> !Screen Shot 2019-03-17 at 3.59.23 AM.png|width=807,height=519!
> 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
>
>
>
--
This message was sent by Atlassian Jira
(v8.3.4#803005)
