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 thesbt
plugin. This project also contains thescripted
tests. -
runner/
: an entry point to all valid combinations of specs and generated formats. See for example how the actual sbt plugin code uses theLagomGenerators
.runner/
also includes integration tests which run faster thanscripted
. -
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 ofParser[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 isgenerate()
which is a function of typeInputStream => 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 theOutput
which represents the filenames and code contents before persisting into actual files. The intermediate stepService => Service
is meant to allow users to inject transformations over the intermediate representation (e.g. to map JSON Schema'sdateTime
toorg.joda.time.Instant
instead ofjava.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 ofParser[T]
- convenience methods for java and scala code generation on
LagomGenerators
- a comprehensive test set (unit tests on parsing, integration tests in
runner/
andscripted
tests demonstrating the complete run of the parser in an sbt project on thelagom-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.