An sbt
plugin to generate Lagom Service Descriptor code (and related entities) provided a Swagger/OpenAPI specification.
Include the plugin dependency on your project/plugins.sbt
file:
addSbtPlugin("com.lightbend.lagom" % "lagom-descriptor-generator-sbt-plugin" % "0.0.2")
and enable the plugin on your project in build.sbt
:
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 sbt
plugin. This project also contains the scripted
tests.
runner/
: an entry point to all valid combinations of specs and generated formats. See for example how the actual sbt plugin code uses the LagomGenerators
. runner/
also includes integration tests which run faster than scripted
.
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 Parser[T]
.
lagom-renderers/
: given an intermediate representation of an API and the models used in it these generate LagomJava and LagomScala code.
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 Output
which represents the filenames and code contents before persisting into actual files. The intermediate step Service => Service
is meant to allow users to inject transformations over the
intermediate representation (e.g. to map JSON Schema's dateTime
to org.joda.time.Instant
instead of 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:
spec-parsers/
providing an implementation of Parser[T]
LagomGenerators
runner/
and scripted
tests demonstrating the complete run of the parser in an sbt project on the lagom-descriptor-generator-sbt-plugin
project)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.
Contributions are very welcome, see CONTRIBUTING.md or skim existing tickets to see where you could help out.