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 wrote:
> On Mon, Apr 8, 2019 at 6:58 PM 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
>
> 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 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.
>
