[jira] [Commented] (FINERACT-733) Swagger Documentation for Fineract API's
[ https://issues.apache.org/jira/browse/FINERACT-733?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17184828#comment-17184828 ] Michael Vorburger commented on FINERACT-733: [~aleks] let's see the Fix Version of this back to 1.4.0, and consider it resolved - as (much!!) work on this topic went into that release. I've moved all open pending sub-tasks to separate JIRA issues, and linked them as Related To here. That way, they can each be independently scheduled for future releases. (You can apply the same pattern for other issues.) > 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 >Assignee: Michael Vorburger >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 strate
[jira] [Commented] (FINERACT-733) Swagger Documentation for Fineract API's
[ https://issues.apache.org/jira/browse/FINERACT-733?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17169561#comment-17169561 ] Michael Vorburger commented on FINERACT-733: This issue has made enough progress that we reasonable well can claim it's part of 1.4.0 already, not just 1.5.0. We can just move whatever sub-tasks won't be completely done out into separate new Enhancement issues for 1.4.0 as we will be doing the release management around when we cut the branch. > 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 >Assignee: Michael Vorburger >Priority: Major > Labels: gsoc2019 > Fix For: 1.4.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
[jira] [Commented] (FINERACT-733) Swagger Documentation for Fineract API's
[ https://issues.apache.org/jira/browse/FINERACT-733?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17156387#comment-17156387 ] Manthan Surkar commented on FINERACT-733: - [~kangbreder] Can you please mark the issues that you have worked on and "completed" as closed? It would be really helpful to keep the track on this project. I cannot be completely sure whether a subtask was completely done or was some part of it was left in your PR (which had too many changes) I have only marked FINERACT-744 as closed as of now. > 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 >Assignee: Michael Vorburger >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
[jira] [Commented] (FINERACT-733) Swagger Documentation for Fineract API's
[ 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 AP
[jira] [Commented] (FINERACT-733) Swagger Documentation for Fineract API's
[ https://issues.apache.org/jira/browse/FINERACT-733?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=16810201#comment-16810201 ] Kang Breder Mbulle commented on FINERACT-733: - Hello [~sanyam96]. I have shared a draft proposal for this project on the GSoC Website. I will be grateful if you can please review and comment. Thank you! > 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 o
[jira] [Commented] (FINERACT-733) Swagger Documentation for Fineract API's
[ https://issues.apache.org/jira/browse/FINERACT-733?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=16808434#comment-16808434 ] KANG BREDER MBULLE commented on FINERACT-733: - Hi [~sanyam96] Thank you for the correction. I have gone through the document. Thank you > 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
[jira] [Commented] (FINERACT-733) Swagger Documentation for Fineract API's
[ https://issues.apache.org/jira/browse/FINERACT-733?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=16806395#comment-16806395 ] Sanyam Goel commented on FINERACT-733: -- Hi [~kangbreder], We are not editing swagger.json/.yml file directly, we are generating by hitting an endpoint specific for generating swagger.json or swagger.yml. Please go through the document and see how we are generating the .json/ .yml You have to add swagger annotations for the missing API's and also have to update current API's and to resolve their current issues [see Goal 1- Goal 6] You also have to check all the mentioned goals and subtasks in this Jira ticket. I will create more subtasks very soon which will help you to understand more about Fineract API's > 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
[jira] [Commented] (FINERACT-733) Swagger Documentation for Fineract API's
[ https://issues.apache.org/jira/browse/FINERACT-733?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=16806365#comment-16806365 ] Vishwas Babu A J commented on FINERACT-733: --- [~kangbreder] : This is indeed a project for GSoc 2019. [~sanyam96] is the mentor for the same. As you have noted, there are a few API's which are absent in the documentation, we would need to add the same as a part of GSOC. [~sanyam96] , can you please respond to the queries that Kang has ? > 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 updati
[jira] [Commented] (FINERACT-733) Swagger Documentation for Fineract API's
[ 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
[jira] [Commented] (FINERACT-733) Swagger Documentation for Fineract API's
[ https://issues.apache.org/jira/browse/FINERACT-733?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=16794715#comment-16794715 ] Sanyam Goel commented on FINERACT-733: -- All the details related to Swagger Integration on Fineract can easily be found at: PDF Link of Documentation: [https://goo.gl/8RMMhN] > 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,
