[jira] [Updated] (FINERACT-733) Swagger Documentation for Fineract API's

["Ed Cable (Jira)" <ji...@apache.org>]

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

Ed Cable updated FINERACT-733:
------------------------------
    Fix Version/s:     (was: 1.4.0)
                   1.5.0

> 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
>
>
> 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)