Hi Phil,
I would point out that:
-- To support HTTP, Lagom uses *Play*. Currently, to create swagger docs for APIs written with Play, you typically use Swagger *annotations*, as supported by
https://github.com/swagger-api/swagger-play/tree/master/play-2.6/swagger-play2.
-- Although the Lagom code generator is the start of another route to Swagger docs, it looks very immature and poorly maintained. See
https://github.com/lagom/lagom/issues/280. (Apologies to Lagom if the code is now maintained elsewhere).
-- Lagom code generator is a *code generator*. That's to say, it is part of your build pipeline.
By contrast:
-- Swakka works with Akka-Http (not play). And, as everybody on this list will testify, Akka-Http is *much* better than Play:-)
-- Swakka does not use the Swagger annotations. Instead, the API metadata goes into *case classes*.
-- Swakka is not a build-time code generator. It uses scala functions at runtime, which are run when the akka-http server boots up.
In my opinion (but only my opinion):
-- Lagom probably makes a lot of sense for an architect in a large organization with a lightbend support contract, trying to achieve consistency of tech across a number of teams. But as a developer, I would not use it. It makes more sense to pick and chose the tools you need on a case by case basis (not to imply that Lagom's stack is poor in any way, but why tie one's self to it?).
-- a key decision for new web projects is often where to use Akka-Http or Play. I hope that, from an API doc perspective, Swakka now makes Akka-Http the better choice, but the overall decision is obviously wider than just API docs.
Hope that is of some help.