[
https://issues.apache.org/jira/browse/FINERACT-733?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=16806268#comment-16806268
]
KANG BREDER MBULLE commented on FINERACT-733:
---------------------------------------------
Hello [~vishwasbabu]. I will like to propose this for GSoC 2019. Currently i
see various tasks listed. Please i will like to have a clean run down of the
various improvements to be done .I will appreciate if i could also get a brief
through on the steps to take in starting the improvement of the documentation.
I have taken a look at the current swagger ui on index.html and have observed
that not all API's on the original documentation have been migrated to the
Swagger documentation,some API's seem to be lacking. Will those also need to be
added? Please can i also have the swagger specification .json file or yml file
which i will use to edit the descriptions in a more detailed form as on the
original documentation?
> 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.4.0
>
> Attachments: Screen Shot 2019-03-17 at 3.59.23 AM.png
>
>
> 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
(v7.6.3#76005)
