Jeremy, do you have familiarity with the Lagom Code Generator project <https://www.lagomframework.com/blog/announcing-lagom-code-generator.html> ? I am interested in building web services using Lightbend technologies (Akka-Http and/or Lagom) while leveraging Swagger documentation of APIs for external clients/consumers. If you have familiarity with stated Lagom project, I'd appreciate your views on the two approaches, i.e. that and Swakka.
Thanks, Phil On Wednesday, January 24, 2018 at 5:18:59 PM UTC-5, Jeremy Townson wrote: > > Hi Akka users, > > This is an update about Swakka, an addon for generating OpenApi/Swagger > docs with Akka-Http. I introduced Swakka in August last year. Back then it > was new, unstable and I recommended people not to use it. > > Yesterday, I cut a v0.5 release. Whilst the library does not cover Swagger > 100%, it does cover everything in the Swagger’s famous PetstoreV2 sample. > Therefore it should document many real world APIs. > > If you are creating Akka-Http endpoints and have a need to document them, > I recommend you check out the project at > https://bitbucket.org/jtownson/swakka/. I hope it would help your project > and I would be really interested to hear your feedback. > > Beyond toughening up the library for a 1.0 release, I am also starting to > consider where to go next with the project. Thoughts in my mind right now > are > — do something completely different > — support for other documentation formats like Api Blueprint or RAML. > — having a close look at Akka-Http’s routing DSL, to see if there is a > refactor that would yield an AST. Now that Swakka can do doc generation > from its OpenApi case class, if it _were_ possible to generate an AST from > a Route structure, it might also be possible to map over that to produce an > instance of OpenApi. Akka-Http users would then have the choice of either > coding an OpenApi instance and getting Swakka to generate Routes, or coding > Routes and generating OpenApi. I’m not convinced this is any more than a > dream and I do not feel I have either the knowledge or authority to go > tinkering with one of the core abstractions in Akka-Http. But if this > interests you, you are familiar with the Akka-Http codebase and want to > take a punt as a pair, I’m game. > > All the best, > Jeremy > > On Monday, 21 August 2017 10:54:44 UTC+1, Jeremy Townson wrote: >> >> Hi Akka Users, >> >> I would like to introduce *Swakka*, a library for adding Swagger/OpenApi >> doc generation to akka-http. https://bitbucket.org/jtownson/swakka. >> >> Like many people I was frustrated by the lack of swagger support in >> akka-http. After reading the proposed solutions to the problem in issue >> 201, "Support Rest API doc generation" ( >> https://github.com/akka/akka-http/issues/201) and trying >> swagger-akka-http (https://github.com/swagger-akka-http/swagger-akka-http), >> I decided to try a different approach. >> >> To briefly describe how Swakka works. One starts by instantiating an >> *OpenApi* case class that represent the structure of an API using >> Openapi/Swagger semantics. Swakka reads this API definition and generates >> (a) an akka-http Route reflecting the swagger structure (extracting the >> parameters, paths, etc in your API definition) and (b) the swagger.json >> itself. The akka-http Route in (a) serves the swagger.json file generated >> in (b) alongside your API. >> >> You provide nested, inner Routes as the implementations of the OpenApi >> endpoints. Thus you still have the full power of akka-http Directives that >> are not supported in Swagger. >> >> It's currently on bitbucket at https://bitbucket.org/jtownson/swakka. I >> might move it to github at some point. It's in a early alpha state, not >> finished, not stable and with quite a few bugs -- so not good for your work >> project yet. Nonetheless I am excited about the principle behind the >> library, so I wanted to put it out there. >> >> If you are willing and able to contribute to Swakka then I would be >> interested to hear from you. The roadmap in my mind for the next 3-6 months >> is >> -- ease of use improvements >> -- full OpenApi 2 support >> -- bugfixes and documentation consistent with 1.0 release. >> >> Read more about it at https://bitbucket.org/jtownson/swakka. >> >> Have fun, >> Jeremy >> >> -- >>>>>>>>>> Read the docs: http://akka.io/docs/ >>>>>>>>>> Check the FAQ: >>>>>>>>>> http://doc.akka.io/docs/akka/current/additional/faq.html >>>>>>>>>> Search the archives: https://groups.google.com/group/akka-user --- You received this message because you are subscribed to the Google Groups "Akka User List" group. To unsubscribe from this group and stop receiving emails from it, send an email to akka-user+unsubscr...@googlegroups.com. To post to this group, send email to akka-user@googlegroups.com. Visit this group at https://groups.google.com/group/akka-user. For more options, visit https://groups.google.com/d/optout.
