We have to tackle one missing point: We have to document our API.

But isn’t the code documentation enough?

No, it is not! Leaving the issues of properly documented code aside, we will concentrate on documenting the API.

The de facto standard in our days seems to be using Swagger for this. To keep things simple, we will stick to it. Besides that, it won’t hurt to have some documentation in text form (a small file could be enough), which should explain the quirks of our API. The bigger the project, the earlier you may encounter flaws in the logic, which might not be changeable because of whatever reasons.

Why do we need documentation?

The lay of the land

Swagger provides a bit of tooling, and there are likely lots of projects trying to bring it to your favorite web framework or tool kit.

In many cases, it might be a good idea to bundle the Swagger UI with our service and make it available on a specific path. Depending on your needs and environment, we’ll want to protect that path via authentication and make it configurable for turning it off in production.

Having the UI, we must decide which path we want to go down.

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.