The dropwizard framework generates Scala code for Dropwizard, using Jackson for serialization.

Server Generation

Prerequisites

In addition to standard Dropwizard dependencies, you’ll need:

  • io.dropwizard:dropwizard-forms
  • com.datasift.dropwizard.scala:dropwizard-scala-core
  • com.fasterxml.jackson.datatype:jackson-datatype-jsr310
  • com.fasterxml.jackson.module:jackson-module-scala
  • org.typelevel:cats-core_${scala_binary_version}

The ScalaBundle from dropwizard-scala should be added in your application’s initialize() method using bootstrap.addBundle().

For each resource generated by guardrail, you’ll need to register it with Jersey in your application’s run() method using environment.jersey.register().

Usage

Server usage follows the same pattern as the Scala akka-http framework. You must implement a Handler class for each resource. Each handler method takes a respond parameter, which allows you to easily construct response instances, plus all parameters specified for the method’s underlying operation. The handler should be passed to the resource class upon construction.

Custom Types

If you need to use a custom type in any guardrail-generated code (via x-scala-type or x-jvm-type), you’ll need to provide implicit GuardrailEncoder, GuardrailDecoder, and GuardrailValidator instances. Usually something like this is all that’s required:

implicit val encodeMyType: GuardrailEncoder[MyType] = GuardrailEncoder.instance
implicit val decodeMyType: GuardrailDecoder[MyType] = GuardrailDecoder.instance(new TypeReference<MyType>() {})
implicit val validateMyType: GuardrailValidator[MyType] = GuardrailValidator.instance

If your type does not work properly with validation for some reason, you can instead use GuardrailValidator.noop.

Your custom implicits can be imported by adding a customImport to your guardrail configuration. See the specific plugin documentation for more information.

Handling Errors

Dropwizard, Jersey, and Jackson do their own validation of input parameters. If validation fails, the resource class method will never be called, and Dropwizard will return a 4xx error with a generic response body. We recommended that you define response codes in your guardrail spec to signal this possibility, and implement and register a Dropwizard ExceptionMapper that outputs response bodies that conform to your spec. In particular, you’ll want to look out for IllegalArgumentException, ValidationException, and subclasses of WebApplicationException that signal 4xx response codes (however, there may be other exceptions thrown).

Similarly, Dropwizard can return 5xx responses when the server is overloaded or if there is some other issue. Again, we recommended you specify and handle this properly by including those response codes in your spec, and handling the appropriate exceptions in your exception mapper.

We recommend that you avoid thrown exceptions for signaling errors, and instead carefully define expected error response codes in your spec. From there, you can use the respond parameter passed to your handler methods to return errors of the proper form. The generated resource methods do handle failed Futures in that they return a generic 500 error with no response body, but that is likely not what your API clients will expect.

Client Generation

Client generation is not yet implemented.