Monthly Archives: March 2013

Using Swagger with Scalatra

If you’re considering Scalatra for your web services, you probably should check out Swagger as a support library. One of its coolest features is possibility to automatically create interactive API docs which you can open in your browser and exercise. The official documentation shows a way to describe your services but it seems that new version offers better way to do that, with safe type references. Let’s take a look at an example to make it clearer (full working app is available on GitHub). This short tutorial does not focus on Scalatra itself and I assume that you have some knowledge on how to configure and use it. We are going to explore the subject of integration with Swagger. Okay, fine, here we go.

Project setup

Our example project is prepared for Scala 2.10 with Scalatra 2.2. Assuming we have a working web app build configuration, we now need to add new dependencies:

“org.scalatra” %% “scalatra-swagger” % “2.2.0”
“com.wordnik” % “swagger-core_2.10.0” % “1.2.0”

Now we have to define a main servlet for Swagger. This servlet will provide our documentation as a service. All other servlet that need to be exposed are going to use this one:

Exposing the browser app

To make your documentation available for exploration and execution via browser, add api-docs web resources to the application. They contain some javascript calling the Swagger servlet and styles, which you can plasy with to customize look and feel of your documentation.

Defining API

Now we can document a simple service. Let’s say we have a servlet consuming simple GET requests with optional query parameter:

It parses a query paramter named “type” and returns an object defined by simple case class ExampleItemList which can be easily transformed to JSON. Now what is this additional parameter defined as operation()? It’s a special definition of API operation defined in additional trait (extending SwaggerSupport):

It’s cool that we can use strong Scala typing to define both parameter and response types. Swagger will manage to expand our custom type (ExampleItemList) and prepare a nice documentation (with an example!).

If you browse http://localhost:8080/api-docs/ now, you can see example endpoint definition:

swagger-api-01

Below, you can fill out a form and send a test request. If you describe a POST and your request body is also going to be represented as a case class, you are given a template to fill, neat!

swagger-api-02

Here’s all the code that you need to make Swagger generate above form for you:

Shortcomings

Swagger has some problems with non-simple class serialization. For example, it cannot handle org.joda.time.DateTime. If you get some crazy exceptions during deployment with vague message, this may be the case.

I hope this short post clarified a bit how can you use Swagger to generate your ‘living documentation’ and utility forms to test services. Hopefully the official Scalatra / Swagger docs get more organized and up-to-date soon.
Special thanks to Michał Ostruszka for discovering all this stuff and sharing it with me!

Advertisements