README.md

sbt-lagom-descriptor-generator

An sbt plugin to generate Lagom Service Descriptor code (and related entities) provided a Swagger/OpenAPI specification.

Usage

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.

Project Status

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.

Project Structure

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.

Supported Specs

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 Parser[T]
• convenience methods for java and scala code generation on LagomGenerators
• a comprehensive test set (unit tests on parsing, integration tests in runner/ and scripted tests demonstrating the complete run of the parser in an sbt project on the lagom-descriptor-generator-sbt-plugin project)

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.

Contributions are very welcome, see CONTRIBUTING.md or skim existing tickets to see where you could help out.