On Mon, Apr 8, 2019 at 6:58 PM Woonsan Ko <woon...@apache.org> 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
I've pushed more and now those three are working fine.
I've noticed that `/admin/deleteLabel/{name}` in documentation was
changed to `/admin/deleteLabelReally/{name}` in code:
-
https://github.com/apache/incubator-s2graph/blob/master/s2http/src/main/scala/org/apache/s2graph/http/S2GraphAdminRoute.scala#L226
There seems to be many in code outdating the documentation. For
example, there are many undocumented operations too. e.g. renameLabel,
copyLabel, swapLabel, etc.
My two cents:
If you folks like the OpenAPI (swagger) document and its UI, then I'd
like to suggest you should keep the swagger doc as the single source
of truth for internal/external developers who are using the APIs,
always keeping it synchronized with the code. So, for example, if
someone makes changes in the REST APIs, it must be affected in the
OpenAPI (swagger) doc, too.
And, consider generating rest api reference documentation through a
tool like [1], and include or link those from the online
documentation.
Then you can minimize the risk of mismatch and outdated API references
and confusing developers who want to use it.
Regards,
Woonsan
[1]
https://github.com/swagger-api/swagger-codegen#generating-static-html-api-documentation
>
> 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
> > > > > > > >
> > > > > >
> > > >
