[
https://issues.apache.org/jira/browse/FINERACT-733?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Vishwas Babu A J updated FINERACT-733:
--------------------------------------
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|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
was:
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 main drop-down menu)
# 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 drop-down menu)
# 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.
> 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
> 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)
