We’re happy to announce the first alpha release of the Lagom Descriptor Generator a project started as a proof-of-concept and that we’ve recently improved. The motivation is to ease consuming third party APIs (be it lagom services, other services on your organization or public APIs in the wild) reducing the amount of code required.
We want Lagom to increase the types of services it can talk to. Until now Lagom was focused on providing RPC via HTTP/JSON as default and we already started working on an gRPC transport for Lagom both for producing services and consuming 3rd party gRPC endpoints.
We had to make a decision since working in both (1) a fully featured code generator from OpenAPI specs to Lagom source code and (a) adding gRPC support into Lagom was beyond our capacity. Today we are calling the community to continue our work in the Lagom code generator while we focus our attention to gRPC. The Lagom Descriptor Generator project may eventually generate Lagom API descriptor sources from seveal API specification format. At the moment only OpenaAPI v2 (aka Swagger specs) is supported.
The Lagom Descriptor Generator is open to community contributions –frequent and infrequent–, everyone helps out. It’s a repo that loves new code and fixes. The Lagom core team will remain in an integrator role, the team will keep an eye on the project to assure its overall coherence but does not fully support it.
The current implementation is a crude generator that will convert a
swagger.json (or yaml) into Lagom API source code. It is currently available as an
sbt plugin but it could be extended into a Maven plugin too. The GitHub repository includes
sbt- on the name but that is a mistake.
The current implementation will read OpenAPI v2 files but we think other API specification formats (e.g. RAML) should be supported too. We added some tips on what should be done to add support for new specification formats.
Finally, this first available release is demoed in the Pet Store application. That sample application adapts the famous Open API Pet Store example into a Lagom application. The Lagom version is made of a LagomJava Pet Service, a LagomScala Store Service and a PlayJava web frontend. Each of the lagom services in the sample application describes its API using an OpenAPI v2 file located in
src/main/openapi/ instead of including the usual
xxx-service-api project separately. Finally, the web frontend uses copies of each of the OpenAPi files it wants to consume. Read the project README.md for more details.