OSDir


[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: Fineract CN - API Documentation


I get your point in Swagger2. Its a duplication effort for our community.

Was trying to check if someone from the community has tried swagger2 for
Fineract CN.

Thanks,
Karthik

On Fri, Sep 28, 2018 at 2:15 PM Isaac Kamga <isaac.kamga@xxxxxxxxx> wrote:

> Hello Karthik and Awasum,
>
> Karthik, I am happy that link helped you get sorted with API Docs.
>
> During an earlier discussion on the mailing list regarding whether or not
> snippets should be checked into the respective repositories, the feedback
> obtained was a BIG NO and rightly so. I went further to check in just the
> required code and wrote the guide out on how developers can obtain
> documentation when they need it. Since we stand for community over code,
> it's left for the community to decide on this.
>
> I also don't know if anyone is experimenting with the Swagger2 tool to do
> API documentation for Fineract CN. IMHO, I think this will be unnecessarily
> duplicating effort whereas there are lots of items on our community roadmap
> <
> https://cwiki.apache.org/confluence/display/FINERACT/Apache+Fineract+CN+Community+Roadmap
> >
> which are yet to be attended to.
>
> At Your Service,
> Isaac Kamga.
>
>
>
>
> On Fri, Sep 28, 2018 at 5:52 AM Karthik Ananthakrishnan
> <karthik.a@xxxxxxxxxxxxxxxx.invalid> wrote:
>
> > Hey Awasum,
> >
> > It would be better to integrate API documentation to the project and
> build
> > such that documentation is generated with build and does not require
> manual
> > updation on every update. Ascii doctor helps in that. We can also look at
> > Swagger2 as another option.
> >
> > Has anyone tried Swagger2 API documentation for Fineract CN.?
> >
> > Thanks,
> > Karthik
> >
> > On Thu, Sep 27, 2018 at 11:55 PM Awasum Yannick <awasum@xxxxxxxxxx>
> wrote:
> >
> > > Hello Isaac, Karthik and others,
> > >
> > > Do you think we need a separate repo which contains the upto date API
> > > documentation for all Fineract CN services?
> > > If we do this, then moving forward, we will have periodically update
> this
> > > repo as soon as an API is created and as features are added.
> > >
> > > Do you think it will be too much work for developers to be manually
> > copying
> > > API docs around? I will like your opinion on this.
> > >
> > > Or Maybe we just request a subdomain such as
> > > fineract-cn-api.fineract.apache.org from Apche Infra and update it
> > > periodically with new changes. What do you think?
> > >
> > > Thanks.
> > > Awasum
> > >
> > > On Thu, Sep 27, 2018 at 6:42 PM Karthik Ananthakrishnan
> > > <karthik.a@xxxxxxxxxxxxxxxx.invalid> wrote:
> > >
> > > > Hello Issac,
> > > >
> > > > Ran the tests successfully and the snippets got generated in the
> > snippets
> > > > folder. I created as empty ascii file which i think is wrong. I will
> > > check
> > > > the link you have provided and try. Is it possible to send me the
> > > > asciidoc.adoc file that you have used.? Will come back if we needed a
> > > call
> > > > to sort this.
> > > >
> > > > Thanks,
> > > > Karthik
> > > >
> > > > On Thu, Sep 27, 2018 at 7:01 PM Isaac Kamga <isaac.kamga@xxxxxxxxx>
> > > wrote:
> > > >
> > > > > Hello Karthik,
> > > > >
> > > > > There are 3 steps involved in getting the API Docs generated. At
> > which
> > > > step
> > > > > did you have issues ? Did you successfully run the unit tests, use
> an
> > > > > asciidoc.adoc
> > > > > <https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/>
> file
> > > to
> > > > > reference the snippets before running `gradle asciidoctor` ? You
> need
> > > to
> > > > > follow the steps in that order to make it work.
> > > > >
> > > > > Ensure you have the right version of gradle, try again and provide
> > > > feedback
> > > > > here. We can set up a call if you like.
> > > > >
> > > > > Cheers,
> > > > > Isaac Kamga.
> > > > >
> > > > > On Tue, Sep 25, 2018 at 7:31 PM Karthik Ananthakrishnan
> > > > > <karthik.a@xxxxxxxxxxxxxxxx.invalid> wrote:
> > > > >
> > > > > > Dear All,
> > > > > >
> > > > > > I was following the steps in the below link to generate API
> > > > documentation
> > > > > > in Fineract CN.
> > > > > > Link:
> > > > > >
> > > > >
> > > >
> > >
> >
> https://cwiki.apache.org/confluence/display/FINERACT/Apache+Fineract+CN+API+Documentation
> > > > > >
> > > > > > When I ran Asciidoctor the documentation is not getting
> generated.
> > A
> > > > HTML
> > > > > > file with timestamp is getting generated.
> > > > > >
> > > > > > [image: AsciiDoctor.png]
> > > > > >
> > > > > > c:\All\fineractcn\fineract-cn-accounting\component-test>gradle
> > > > > asciidoctor
> > > > > > > Task :asciidoctor
> > > > > > io/console not supported; tty will not be manipulated
> > > > > >
> > > > > > Deprecated Gradle features were used in this build, making it
> > > > > incompatible
> > > > > > with Gradle 5.0.
> > > > > > Use '--warning-mode all' to show the individual deprecation
> > warnings.
> > > > > > See
> > > > > >
> > > > >
> > > >
> > >
> >
> https://docs.gradle.org/4.10.1/userguide/command_line_interface.html#sec:command_line_warnings
> > > > > >
> > > > > > BUILD SUCCESSFUL in 1m 32s
> > > > > > 1 actionable task: 1 executed
> > > > > >
> > > > > > Can someone help me understand what i am missing.?
> > > > > >
> > > > > > Thanks,
> > > > > > Karthik
> > > > > >
> > > > >
> > > >
> > >
> >
>