Hi Do Yung, I see your point. Native support in Scala + Akka is better than manual edits, of course. There seems to be many more different libraries at the moment in Scala ecosystem than Java's, like this one too: - https://github.com/swagger-akka-http/swagger-akka-http
I'm not yet experienced much in Scala web application framework world, so I can't really judge them. ;-) So, I'm open to you guys' opinions and preferences. What do others think? Regards, Woonsan On Wed, May 1, 2019 at 4:31 AM DO YUNG YOON <sho...@gmail.com> wrote: > > Hi Woonsan. > > Sorry for the late response. It took me for a while to figure out what > would be a nice way for working with OpenAPI document spec. > > I agree with your two cents, especially the importance of generating rest > API reference through the right tool. > > Here is the tools I played with a little bit. > > - tapir: https://github.com/softwaremill/tapir > - endpoints: http://julienrf.github.io/endpoints/index.html > > Personally, I prefer tapir, but it seems like it does not provide scala > 2.11 available on maven central. I spent few days to upgrade scala version > from 2.11 to 2.12, but realize it is not that easy(we may need to open up a > separate discussion how we are going to upgrade scala version to 2.12). > > so just played with endpoints at this point and just sharing it with you to > check if we are doing the right thing. > > here is how to test this PR( > https://github.com/woonsan/incubator-s2graph/pull/1) > > 1. setup docker image on local for hbase. > > cd dev_support; docker-compose up graph_hbase > > 2. run akka http server in dev environment. > > sbt 'project s2http' '~reStart' > > 3. check the specs that generated by documentation server/spec. > > http://localhost:8000/api-docs/documentation.json > > 4. check the AdminEndpoints > > this is where our admin specs will reside on. > I added few more specs for listing service/label/serviceColumns etc to > validate if they are working. > > ex) > - localhost:8000/admin/listServices > - localhost:8000/admin/listLabels > - localhost:8000/admin/listServiceColumns/s2graph > > IMAO, The nice thing about the above two libraries is that it separates the > implementation and spec but still validate it on compile time, which I > prefer over the annotation approach. > I think it takes some time to get used to it for the first time, then after > struggling, the library shine and basically, help us to synchronize API and > doc so worth it. > > Please review and give any comments. > > On Wed, Apr 10, 2019 at 8:24 AM Woonsan Ko <woon...@apache.org> wrote: > > > 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 > > > > > > > > > > > > > > > > > > > > > > > > > >
