sbt plugin to generate Lagom Service Descriptor code (and related entities) provided a Swagger/OpenAPI specification.
Include the plugin dependency on your
addSbtPlugin("com.lightbend.lagom" % "lagom-descriptor-generator-sbt-plugin" % "0.0.2")
and enable the plugin on your project in
lazy val ``service-api = (project in file("service-api")) .enablePlugins(LagomJava && LagomOpenApiPlugin) .settings( libraryDependencies ++= Seq( lagomJavadslApi ) )
The plugin will trigger the Java or Scala code generation depending on the dependencies included in your code.
DISCLAIMER Currently the build job in Travis fails. Solve #20 to fix that.
This plugin is not ready for production. It currently works in most happy scenarios when given one or many JSON or YAML OpenAPI V2 specification files. There is a minimal set of
scripted tests (1, 2, 3) demonstrating the basic functionality available.
This project provides an
sbt plugin that will generate the Lagom Service Descriptor given a 3rd party API specification. It works by detecting the dependency of the project on Lagom and also the Java vs Scala API. Once the plugin is activated it will locate all 3rd party specification files and proceed with the code genreations.
lagom-descriptor-generator-sbt-plugin: the code for the
sbtplugin. This project also contains the
runner/: an entry point to all valid combinations of specs and generated formats. See for example how the actual sbt plugin code uses the
runner/also includes integration tests which run faster than
spec-parsers/: contains each of the 3rd party specicication parsers. Implementors of a new format should create a project in this directory providing an implementation of
generator-api/: all modelling required for the generator. The key part is
generate()which is a function of type
InputStream => Spec => Service => Service => Output. That is a 4 step tranformation: going through the specification file to the 3rd party specification representation, then the intermediate representation (API and models) and finally the
Outputwhich represents the filenames and code contents before persisting into actual files. The intermediate step
Service => Serviceis meant to allow users to inject transformations over the intermediate representation (e.g. to map JSON Schema's
java.time.Instant). See other potential applications of this transformation on the issues list.
OpenAPI V2 placing JSON or YAML OpenAPI V2 files in a project's
src/main/openapi will generate the required code to represent that spec using Lagom code. See the
scripted tests for an example.
Supporting new spec formats would require:
- a new project on
spec-parsers/providing an implementation of
- convenience methods for java and scala code generation on
- a comprehensive test set (unit tests on parsing, integration tests in
scriptedtests demonstrating the complete run of the parser in an sbt project on the
Contributions & Maintainers
This project does not have contributors, it only has maintainers—frequent and infrequent—and everyone helps out. This repo loves new maintainers as well as old maintainers. :-) The Lagom core team keeps an eye on the project to assure its overall coherence but does not fully support this sbt plugin.