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 <woon...@apache.org> wrote:
>
> On Thu, Mar 28, 2019 at 9:19 AM DO YUNG YOON <sho...@gmail.com> 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 <woon...@apache.org> 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 <sho...@gmail.com> 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
> > > > <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 <woon...@apache.org> 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 <sho...@gmail.com> 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 <woon...@apache.org>
> > > 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 to propose the following:
> > > > > > > 1. Initially one of the committers should generate the site html
> > > from
> > > > > > > the doc/ in git source repo, following the instruction in
> > > > > > > doc/readme.md, until `make html`, which generates all the html and
> > > > > > > other static resource files at docs/build/html/. (I've just tested
> > > and
> > > > > > > it works fine.)
> > > > > > > And, the generated files at docs/build/html/** should be
> > > committed
> > > > > > > to a new directory, "docs", in [3].
> > > > > > > 2. Change the "Docs" menu link to "docs/index.html" from the
> > > external
> > > > > link.
> > > > > > > 3. From now on, whenever committers update documentation, once in
> > > > > > > a
> > > > > > > while, do the step 1 and 2 periodically, to synchronize the online
> > > > > > > site with the documentation source.
> > > > > > >
> > > > > > > When we really want to expand the community during the incubation
> > > > > > > period, the online documentation is really crucial: new comers
> > > start
> > > > > > > from there...
> > > > > > >
> > > > > > > Any thoughts?
> > > > > > > If this sounds okay, any volunteers?
> > > > > > >
> > > > > > > Regards,
> > > > > > >
> > > > > > > Woonsan
> > > > > > >
> > > > > > > [1] http://s2graph.incubator.apache.org/
> > > > > > > [2] https://steamshon.gitbooks.io/s2graph-book/content/
> > > > > > > [3] http://svn.apache.org/repos/asf/incubator/s2graph/site/
> > > > > > > [4] https://issues.apache.org/jira/browse/INFRA-11806
> > > > > > >
> > > > >
> > >
