Write a swagger.yml file describing our API, create JSON from it, and deliver that as an asset.

Create the JSON dynamically via some library at runtime.

Which path should we take?

Let’s now compare the pros and cons of both these approaches.

Using swagger.yml Using a library

Provides a description that is more or less set in stone Provides a description that reflects our actual code

Avoids possible performance impacts and other quirks at runtime Results in generating “funny” deduced data types like Future1 and so on

We have to figure out a way to test that the service delivers what it describes Makes extensive use of annotations to make our API description usable

Tightly bounds the code and description Decouples the code and description

A common tool for the first approach is the Swagger Editor.

For those favoring the impure approach, there is the swagger-akka-http library.

But can’t we do better than this?

The answer is yes! We can describe our API using static typing, have the compiler check it, and deduce server and client code.

To be fair, Swagger is also intended to auto-generate code from it, but often (if not always), these are one-shot throw-away solutions because we lose our modifications if the code needs to be re-generated.