Re: Swagger Doc and UI support (Was: Documentation to the official online site svn?)
Cool! Thank you sir!
Woonsan
On Tue, Apr 9, 2019 at 8:48 AM DO YUNG YOON wrote:
>
> Hi Woonsan. Sorry for the late reply.
>
> I really appreciate getting involved and I would love to review it.
> I will read through the PR on this week, then ask any questions on this
> thread.
>
> Thanks for your contribution!
>
> On Tue, Apr 9, 2019 at 7:58 AM Woonsan Ko wrote:
>
> > Hi Daewon, Do Yung and/or anyone interested in,
> >
> > I've just submitted a PR which has the swagger UI support with the
> > default swagger document, initially for admin services:
> > - https://github.com/apache/incubator-s2graph/pull/197
> >
> > I think Swagger UI with the default swagger doc for the APIs will make
> > it easier for many devs.
> > Could you please review it?
> >
> > I figured out how to add /api-docs route there, but feel free to
> > correct it if I didn't follow any (Scala or Akka) best practices. ;-)
> >
> > As described in the PR description, the following operations work fine
> > with the examples:
> > - /admin/createService, /admin/createLabel, /admin/addIndex,
> > /admin/getLabel/{name}
> >
> > But, the following returns 404, for some reason which I can't figure out
> > now:
> > - /admin/deleteLabel/{name}, /admin/addProp/{name},
> > /admin/createServiceColumn
> >
> > Kind regards,
> >
> > Woonsan
> >
> > On Thu, Mar 28, 2019 at 9:45 AM Woonsan Ko wrote:
> > >
> > > On Thu, Mar 28, 2019 at 9:19 AM DO YUNG YOON wrote:
> > > >
> > > > +1 for 'running' examples and would be happy to help if there is
> > anything I
> > > > can help with.
> > > >
> > > > Also while I was going through the documentation to check if it is
> > correct,
> > > > I found it is a bit tedious to copy payload on the doc to rest
> > client(such
> > > > as postman).
> > > > I wish there was a documentation tool integration, such as swagger,
> > which
> > > > also provides specs and UI to try each endpoint with examples.
> > > > I think integration with documentation tools is good for not only for
> > users
> > > > but also developers who set up local development environments and fix
> > code
> > > > and testing.
> > > >
> > > > Any thoughts?
> > >
> > > +1
> > > Great idea!
> > > If we provide a swagger UI (e.g, http://localhost:8000/api-docs), it
> > > will really boost developers understanding!
> > > We can probably include swagger UI under the /api-docs endpoint with a
> > > swagger.{json|yaml} file. I'm not accustomed to the scala web
> > > framework, but if someone expose a simple index.html under the
> > > /api-docs, then I can contribute or help create a pull request to
> > > enable swagger UI.
> > >
> > > Cheers,
> > >
> > > Woonsan
> > >
> > > >
> > > >
> > > > On Thu, Mar 28, 2019 at 10:05 PM Woonsan Ko
> > wrote:
> > > >
> > > > > Wow, this is great!!!
> > > > > Thank you very much.
> > > > >
> > > > > As a side note, I'll try to follow the documentation to implement
> > > > > something simple -- by using S2Graph of course -- such as "Related
> > > > > articles" or "Related products" which are really popular use cases in
> > > > > most websites nowadays, but it's hard to implement actually in an
> > > > > automated way based on users' behaviors.
> > > > > If we have simple 'running' examples somewhere for normal web
> > > > > developers, I think it would help people adopt this project and
> > > > > solutions.
> > > > >
> > > > > Cheers,
> > > > >
> > > > > Woonsan
> > > > >
> > > > > On Thu, Mar 28, 2019 at 8:02 AM DO YUNG YOON
> > wrote:
> > > > > >
> > > > > > Hi Woonsan, Sorry for being late.
> > > > > >
> > > > > > I followed the instructions and the changes are now pushed to svn.
> > > > > >
> > > > > > Here is the updates
> > > > > >
> > > > > > - svn: https://svn.apache.org/repos/asf/incubator/s2graph/site
> > (revision
> > > > > > 1856470)
> > > > > > - doc link on incubator site: *
> > > > > https://s2graph.apache.org/docs/index.html
> > > > > > *
> > > > > >
> > > > > > Please check the updates and feel free to comment
> > > > > >
> > > > > >
> > > > > > On Tue, Mar 5, 2019 at 11:10 PM Woonsan Ko
> > wrote:
> > > > > >
> > > > > > > Thanks a lot, Do Yung, as always!
> > > > > > > Please tell me if there's anything I can help with.
> > > > > > >
> > > > > > > Cheers,
> > > > > > >
> > > > > > > Woonsan
> > > > > > >
> > > > > > > On Tue, Mar 5, 2019 at 12:12 AM DO YUNG YOON
> > wrote:
> > > > > > > >
> > > > > > > > Hi Woonsan.
> > > > > > > >
> > > > > > > > I agree with your suggestion, and I am volunteering for this.
> > > > > > > > Let me try working on this on weekends then I will share any
> > > > > > > > questions/updates.
> > > > > > > >
> > > > > > > > Thanks for your suggestion.
> > > > > > > >
> > > > > > > >
> > > > > > > > On Tue, Mar 5, 2019 at 11:27 AM Woonsan Ko > >
> > > > > wrote:
> > > > > > > >
> > > > > > > > > Hi folks,
> > > > > > > > >
> > > > > > > > > At the moment, the "Docs" link at the top menu bar [1] is
> > linked
> > > > > to a
> > > > > > >
Re: Swagger Doc and UI support (Was: Documentation to the official online site svn?)
Hi Woonsan. Sorry for the late reply.
I really appreciate getting involved and I would love to review it.
I will read through the PR on this week, then ask any questions on this
thread.
Thanks for your contribution!
On Tue, Apr 9, 2019 at 7:58 AM Woonsan Ko wrote:
> Hi Daewon, Do Yung and/or anyone interested in,
>
> I've just submitted a PR which has the swagger UI support with the
> default swagger document, initially for admin services:
> - https://github.com/apache/incubator-s2graph/pull/197
>
> I think Swagger UI with the default swagger doc for the APIs will make
> it easier for many devs.
> Could you please review it?
>
> I figured out how to add /api-docs route there, but feel free to
> correct it if I didn't follow any (Scala or Akka) best practices. ;-)
>
> As described in the PR description, the following operations work fine
> with the examples:
> - /admin/createService, /admin/createLabel, /admin/addIndex,
> /admin/getLabel/{name}
>
> But, the following returns 404, for some reason which I can't figure out
> now:
> - /admin/deleteLabel/{name}, /admin/addProp/{name},
> /admin/createServiceColumn
>
> Kind regards,
>
> Woonsan
>
> On Thu, Mar 28, 2019 at 9:45 AM Woonsan Ko wrote:
> >
> > On Thu, Mar 28, 2019 at 9:19 AM DO YUNG YOON wrote:
> > >
> > > +1 for 'running' examples and would be happy to help if there is
> anything I
> > > can help with.
> > >
> > > Also while I was going through the documentation to check if it is
> correct,
> > > I found it is a bit tedious to copy payload on the doc to rest
> client(such
> > > as postman).
> > > I wish there was a documentation tool integration, such as swagger,
> which
> > > also provides specs and UI to try each endpoint with examples.
> > > I think integration with documentation tools is good for not only for
> users
> > > but also developers who set up local development environments and fix
> code
> > > and testing.
> > >
> > > Any thoughts?
> >
> > +1
> > Great idea!
> > If we provide a swagger UI (e.g, http://localhost:8000/api-docs), it
> > will really boost developers understanding!
> > We can probably include swagger UI under the /api-docs endpoint with a
> > swagger.{json|yaml} file. I'm not accustomed to the scala web
> > framework, but if someone expose a simple index.html under the
> > /api-docs, then I can contribute or help create a pull request to
> > enable swagger UI.
> >
> > Cheers,
> >
> > Woonsan
> >
> > >
> > >
> > > On Thu, Mar 28, 2019 at 10:05 PM Woonsan Ko
> wrote:
> > >
> > > > Wow, this is great!!!
> > > > Thank you very much.
> > > >
> > > > As a side note, I'll try to follow the documentation to implement
> > > > something simple -- by using S2Graph of course -- such as "Related
> > > > articles" or "Related products" which are really popular use cases in
> > > > most websites nowadays, but it's hard to implement actually in an
> > > > automated way based on users' behaviors.
> > > > If we have simple 'running' examples somewhere for normal web
> > > > developers, I think it would help people adopt this project and
> > > > solutions.
> > > >
> > > > Cheers,
> > > >
> > > > Woonsan
> > > >
> > > > On Thu, Mar 28, 2019 at 8:02 AM DO YUNG YOON
> wrote:
> > > > >
> > > > > Hi Woonsan, Sorry for being late.
> > > > >
> > > > > I followed the instructions and the changes are now pushed to svn.
> > > > >
> > > > > Here is the updates
> > > > >
> > > > > - svn: https://svn.apache.org/repos/asf/incubator/s2graph/site
> (revision
> > > > > 1856470)
> > > > > - doc link on incubator site: *
> > > > https://s2graph.apache.org/docs/index.html
> > > > > *
> > > > >
> > > > > Please check the updates and feel free to comment
> > > > >
> > > > >
> > > > > On Tue, Mar 5, 2019 at 11:10 PM Woonsan Ko
> wrote:
> > > > >
> > > > > > Thanks a lot, Do Yung, as always!
> > > > > > Please tell me if there's anything I can help with.
> > > > > >
> > > > > > Cheers,
> > > > > >
> > > > > > Woonsan
> > > > > >
> > > > > > On Tue, Mar 5, 2019 at 12:12 AM DO YUNG YOON
> wrote:
> > > > > > >
> > > > > > > Hi Woonsan.
> > > > > > >
> > > > > > > I agree with your suggestion, and I am volunteering for this.
> > > > > > > Let me try working on this on weekends then I will share any
> > > > > > > questions/updates.
> > > > > > >
> > > > > > > Thanks for your suggestion.
> > > > > > >
> > > > > > >
> > > > > > > On Tue, Mar 5, 2019 at 11:27 AM Woonsan Ko >
> > > > wrote:
> > > > > > >
> > > > > > > > Hi folks,
> > > > > > > >
> > > > > > > > At the moment, the "Docs" link at the top menu bar [1] is
> linked
> > > > to a
> > > > > > > > non-ASF URL [2].
> > > > > > > > I don't think we can keep the non-ASF pages there in the
> future.
> > > > > > > > Furthermore, the documentation there is outdated from the
> > > > > > > > documentation source at doc/.
> > > > > > > >
> > > > > > > > Our official documentation repository is the SVN [3], as of
> [4].
> > > > > > > >
> > > > > > > > Therefore, I'd like
