You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@fineract.apache.org by Sanyam Goel <sa...@gmail.com> on 2017/07/11 14:46:17 UTC

[ Suggestions and Feedback ] on Swagger Implementation for Live Documentation for FINERACT API on POST and PUT endpoints | GSoC’17

Hi Mifos and Fineract community,

Mifos’ internal REST endpoint API uses in most cases serialized JSON
objects as string parameters to pass complex objects. These strings are
then deserialized by helper classes of Mifos. *The problem with is that the
Swagger cannot deduct any clues about these objects and thus just
interprets them as simple strings* as there’s no bean assigned. Please
review the attached and send any feedback with the suggested approach for
Swagger implementation or with any new approach

Please see document attached

Link to Document: https://goo.gl/rL3zdF

Thanks,


-- 
SANYAM GOEL
Bharati Vidyapeeth's College Of Engineering, New Delhi, India
Github: https://github.com/sanyam96
Hackerrank: https://www.hackerrank.com/sanyam_goel
+91-9818060934

Re: [ Suggestions and Feedback ] on Swagger Implementation for Live Documentation for FINERACT API on POST and PUT endpoints | GSoC’17

Posted by Ed Cable <ed...@mifos.org>.
Hi Aleks,

Thanks for steering Sanyam to a recommend approach of the three he
proposed. I'm glad he's now following that.

Sanyam, please continue to keep updating the community as you continue your
work on this project for GSOC.

Ed

On Sat, Jul 22, 2017 at 1:05 PM, Aleksandar Vidakovic <
cheetah@monkeysintown.com> wrote:

> Hi all,
>
> ... I just had a conversation with Sanyam about his latest idea how to
> solve the documentation issues and I think he found a very nice approach.
> It's easy to adopt with the current code base (and its challenges of
> documenting it), doesn't conflict with the existing code base and doesn't
> bloat the existing Javadoc above the methods in the JAX-RS XXXApiResource
> classes. There is a bit of overhead code to compensate for the missing type
> information in the JAX-RS resource classes, but I think it's as minimal as
> possible without major refactoring of Mifo's existing code.
>
> Please have a look at for an example:
>
>    - https://github.com/Sanyam96/incubator-fineract/blob/
>    testPOJO/fineract-provider/src/main/java/org/apache/
>    fineract/accounting/closure/api/GLClosuresApiResource.java#L129
>    <https://github.com/Sanyam96/incubator-fineract/blob/testPOJO/fineract-provider/src/main/java/org/apache/fineract/accounting/closure/api/GLClosuresApiResource.java#L129>
>    - https://github.com/Sanyam96/incubator-fineract/blob/
>    testPOJO/fineract-provider/src/main/java/org/apache/
>    fineract/accounting/closure/api/GLClosuresApiResourceSwagger.java
>    <https://github.com/Sanyam96/incubator-fineract/blob/testPOJO/fineract-provider/src/main/java/org/apache/fineract/accounting/closure/api/GLClosuresApiResourceSwagger.java>
>
> As you can see he's using approach #2 described in his proposal document (
> https://goo.gl/rL3zdF); he uses simple bean classes that just serve the
> purpose of documenting the API. That might sound a bit like overhead, but I
> really think this is the most efficient approach (please chime in if you
> see improvements). Some niceties I want to point out:
>
>    - non of the "documentation bean classes" (see in
>    "GLClosuresApiResourceSwagger") can be instantiated due to a private
>    constructor; this is to make it clear that these classes are for
>    documentation only
>    - to reduce boilerplate code he just added public class attributes
>    with Swagger annotations (i. e. no senseless getter-setter code); this is
>    just enough to make the Swagger infrastructure create the correct metadata
>    for the live documentation; really easy to maintain
>    - all classes that are only used to enhance the Swagger annotations
>    are contained in a container class; to make it clear where they belong the
>    container class is named after the JAX-RS class with the suffix "Swagger"
>    (e. g. GLClosuresApiResource -> GLClosuresApiResourceSwagger). JAX-RS and
>    docuemntation classes are then ordered next to each other in IDEs. The
>    container class itself can't be instantiated neither (again private
>    constructor) to really make sure this stuff is just used for documentation.
>    Another nice little twist: the documentation bean class container ("
>    GLClosuresApiResourceSwagger") is only package visible which should
>    further help to not shoot yourself in the foot
>    - from what I see his changes should be easy to merge back to the
>    upstream project; Sanyam is practically only adding a couple of annotations
>    in the JAX-RS classes
>
> +1 for this approach
>
> Cheers,
>
> Aleks
>
>
> On Sat, Jul 22, 2017 at 6:13 PM Ed Cable <ed...@mifos.org> wrote:
>
>> Hello Fineracters,
>>
>> Sanyam has been patiently awaiting feedback for nearly two weeks and is
>> blocked in proceeding forward with his project. He and the community as a
>> whole would greatly appreciate some of the senior developers who interact
>> with the APis the most to review and reply to the three scenarios he's
>> outlined in his Google Doc.
>>
>> Thanks,
>>
>> Ed
>>
>> On Tue, Jul 11, 2017 at 7:46 AM, Sanyam Goel <sa...@gmail.com>
>> wrote:
>>
>>> Hi Mifos and Fineract community,
>>>
>>> Mifos’ internal REST endpoint API uses in most cases serialized JSON
>>> objects as string parameters to pass complex objects. These strings are
>>> then deserialized by helper classes of Mifos. *The problem with is that
>>> the Swagger cannot deduct any clues about these objects and thus just
>>> interprets them as simple strings* as there’s no bean assigned. Please
>>> review the attached and send any feedback with the suggested approach for
>>> Swagger implementation or with any new approach
>>>
>>> Please see document attached
>>>
>>> Link to Document: https://goo.gl/rL3zdF
>>>
>>> Thanks,
>>>
>>>
>>> --
>>> SANYAM GOEL
>>> Bharati Vidyapeeth's College Of Engineering, New Delhi, India
>>> Github: https://github.com/sanyam96
>>> Hackerrank: https://www.hackerrank.com/sanyam_goel
>>> +91-9818060934 <+91%2098180%2060934>
>>>
>>
>>
>>
>> --
>> *Ed Cable*
>> President/CEO, Mifos Initiative
>> edcable@mifos.org | Skype: edcable | Mobile: +1.484.477.8649
>> <+1%20484-477-8649>
>>
>> *Collectively Creating a World of 3 Billion Maries | *http://mifos.org
>> <http://facebook.com/mifos>  <http://www.twitter.com/mifos>
>>
>>


-- 
*Ed Cable*
President/CEO, Mifos Initiative
edcable@mifos.org | Skype: edcable | Mobile: +1.484.477.8649

*Collectively Creating a World of 3 Billion Maries | *http://mifos.org
<http://facebook.com/mifos>  <http://www.twitter.com/mifos>

Re: [ Suggestions and Feedback ] on Swagger Implementation for Live Documentation for FINERACT API on POST and PUT endpoints | GSoC’17

Posted by Aleksandar Vidakovic <ch...@monkeysintown.com>.
Hi all,

... I just had a conversation with Sanyam about his latest idea how to
solve the documentation issues and I think he found a very nice approach.
It's easy to adopt with the current code base (and its challenges of
documenting it), doesn't conflict with the existing code base and doesn't
bloat the existing Javadoc above the methods in the JAX-RS XXXApiResource
classes. There is a bit of overhead code to compensate for the missing type
information in the JAX-RS resource classes, but I think it's as minimal as
possible without major refactoring of Mifo's existing code.

Please have a look at for an example:

   -
   https://github.com/Sanyam96/incubator-fineract/blob/testPOJO/fineract-provider/src/main/java/org/apache/fineract/accounting/closure/api/GLClosuresApiResource.java#L129
   -
   https://github.com/Sanyam96/incubator-fineract/blob/testPOJO/fineract-provider/src/main/java/org/apache/fineract/accounting/closure/api/GLClosuresApiResourceSwagger.java

As you can see he's using approach #2 described in his proposal document (
https://goo.gl/rL3zdF); he uses simple bean classes that just serve the
purpose of documenting the API. That might sound a bit like overhead, but I
really think this is the most efficient approach (please chime in if you
see improvements). Some niceties I want to point out:

   - non of the "documentation bean classes" (see in
   "GLClosuresApiResourceSwagger") can be instantiated due to a private
   constructor; this is to make it clear that these classes are for
   documentation only
   - to reduce boilerplate code he just added public class attributes with
   Swagger annotations (i. e. no senseless getter-setter code); this is just
   enough to make the Swagger infrastructure create the correct metadata for
   the live documentation; really easy to maintain
   - all classes that are only used to enhance the Swagger annotations are
   contained in a container class; to make it clear where they belong the
   container class is named after the JAX-RS class with the suffix "Swagger"
   (e. g. GLClosuresApiResource -> GLClosuresApiResourceSwagger). JAX-RS and
   docuemntation classes are then ordered next to each other in IDEs. The
   container class itself can't be instantiated neither (again private
   constructor) to really make sure this stuff is just used for documentation.
   Another nice little twist: the documentation bean class container
   ("GLClosuresApiResourceSwagger") is only package visible which should
   further help to not shoot yourself in the foot
   - from what I see his changes should be easy to merge back to the
   upstream project; Sanyam is practically only adding a couple of annotations
   in the JAX-RS classes

+1 for this approach

Cheers,

Aleks


On Sat, Jul 22, 2017 at 6:13 PM Ed Cable <ed...@mifos.org> wrote:

> Hello Fineracters,
>
> Sanyam has been patiently awaiting feedback for nearly two weeks and is
> blocked in proceeding forward with his project. He and the community as a
> whole would greatly appreciate some of the senior developers who interact
> with the APis the most to review and reply to the three scenarios he's
> outlined in his Google Doc.
>
> Thanks,
>
> Ed
>
> On Tue, Jul 11, 2017 at 7:46 AM, Sanyam Goel <sa...@gmail.com>
> wrote:
>
>> Hi Mifos and Fineract community,
>>
>> Mifos’ internal REST endpoint API uses in most cases serialized JSON
>> objects as string parameters to pass complex objects. These strings are
>> then deserialized by helper classes of Mifos. *The problem with is that
>> the Swagger cannot deduct any clues about these objects and thus just
>> interprets them as simple strings* as there’s no bean assigned. Please
>> review the attached and send any feedback with the suggested approach for
>> Swagger implementation or with any new approach
>>
>> Please see document attached
>>
>> Link to Document: https://goo.gl/rL3zdF
>>
>> Thanks,
>>
>>
>> --
>> SANYAM GOEL
>> Bharati Vidyapeeth's College Of Engineering, New Delhi, India
>> Github: https://github.com/sanyam96
>> Hackerrank: https://www.hackerrank.com/sanyam_goel
>> +91-9818060934 <+91%2098180%2060934>
>>
>
>
>
> --
> *Ed Cable*
> President/CEO, Mifos Initiative
> edcable@mifos.org | Skype: edcable | Mobile: +1.484.477.8649
> <+1%20484-477-8649>
>
> *Collectively Creating a World of 3 Billion Maries | *http://mifos.org
> <http://facebook.com/mifos>  <http://www.twitter.com/mifos>
>
>

Re: [ Suggestions and Feedback ] on Swagger Implementation for Live Documentation for FINERACT API on POST and PUT endpoints | GSoC’17

Posted by Ed Cable <ed...@mifos.org>.
Hello Fineracters,

Sanyam has been patiently awaiting feedback for nearly two weeks and is
blocked in proceeding forward with his project. He and the community as a
whole would greatly appreciate some of the senior developers who interact
with the APis the most to review and reply to the three scenarios he's
outlined in his Google Doc.

Thanks,

Ed

On Tue, Jul 11, 2017 at 7:46 AM, Sanyam Goel <sa...@gmail.com>
wrote:

> Hi Mifos and Fineract community,
>
> Mifos’ internal REST endpoint API uses in most cases serialized JSON
> objects as string parameters to pass complex objects. These strings are
> then deserialized by helper classes of Mifos. *The problem with is that
> the Swagger cannot deduct any clues about these objects and thus just
> interprets them as simple strings* as there’s no bean assigned. Please
> review the attached and send any feedback with the suggested approach for
> Swagger implementation or with any new approach
>
> Please see document attached
>
> Link to Document: https://goo.gl/rL3zdF
>
> Thanks,
>
>
> --
> SANYAM GOEL
> Bharati Vidyapeeth's College Of Engineering, New Delhi, India
> Github: https://github.com/sanyam96
> Hackerrank: https://www.hackerrank.com/sanyam_goel
> +91-9818060934 <+91%2098180%2060934>
>



-- 
*Ed Cable*
President/CEO, Mifos Initiative
edcable@mifos.org | Skype: edcable | Mobile: +1.484.477.8649

*Collectively Creating a World of 3 Billion Maries | *http://mifos.org
<http://facebook.com/mifos>  <http://www.twitter.com/mifos>