By Steve Song on April 29, 2016
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 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.
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.
- Add sbt-swagger config/dependency in your SBT build file
- Add docs in your Scala code with JAX-RS (jsr311) annotations
- run sbt swagger