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 <[email protected]> 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 <[email protected]> > 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 > [email protected] | 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> > >
