The Problem

A result of migrating our monolithic system towards microservices in the last couple of years is 20+ internal services (so far). Many of these services lacked great API documentation, the kind where our developers could easily grasp all endpoints, behaviours, and error codes. We needed three things for our API documentation: a common and easy way to document each endpoint of every service, a centralized location to access all this documentation, and a way to automatically update after changes to an endpoint. Swagger to the rescue.

Swagger

swagger

Swagger is a specification and complete framework implementation for describing, producing, consuming, and visualizing RESTful web services. It also comes with Swagger UI, a great documentation viewer for endpoints. It lists endpoints and details of each one, and also provides a UI that can actually run test queries against test servers. Another bonus is that Swagger documentation is done with annotations in source code and so reduces overhead of managing multiple document sources. Sounds good!

  • Swagger documentation library for Play framework? Check.
  • Swagger documentation library for arbitrary Java web apps? Check.
  • Swagger documentation for endpoints in general for Scala? Nope.

sbt-swagger

No Swagger for Scala endpoints? OK, let’s help. We made sbt-swagger Scala Library as an SBT plugin. Our sbt-swagger sbt plugin generates swagger-ui compatible JSON data based on the Swagger & JAX-RS (jsr311) annotations in your code. Any Scala applications that provide APIs can benefit from this plugin.

Today, we released it as open source. We have been using sbt-swagger in our products for documenting, exclusively for our internal Scala microservice component that provides our internal protocol over ZeroMQ.

Using sbt-swagger

Three steps:

  1. Add sbt-swagger config/dependency in your SBT build file
  2. Add docs in your Scala code with JAX-RS (jsr311) annotations
  3. run sbt swagger

You will get JSON files in target/swagger that swagger-ui can render.

Details can be found in the README file on the GitHub page.

Sample project using sbt-swagger

Take a look at the code – specifically, how SBT configs are set, and how annotations are written in the code. Sample output from sbt swagger shows that it generates 2 json files; swagger-ui will render them beautifully later.

The full functioning sample is found here: sbt-swagger-example

swagger UI

Swagger UI in Action

Summary

The rising popularity of APIs and programmable web, good documentation should never be a second thought. It increases understandability and promotes better developer experience. Swagger is a great tool for achieving this and we have enjoyed success with it at Hootsuite. We hope our offering can come in handy in your project. Give it a try and let us know what you think.

About the Author

Steve Song

Steve is a Software Developer on the Platform Team at Hootsuite. When not writing distributed and scalable microservices in Scala, he likes to explore beautiful Vancouver, read books, and discover technology. Follow Steve on Twitter @ssongvan