Documenting Our API
Explore how to effectively document your Scala-based HTTP API using Swagger and related tools. Understand the differences between static swagger.yml files and dynamic API generation. Learn to balance code-description consistency and performance, and how to secure and test your API documentation effectively.
We'll cover the following...
Do we need documentation?
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 ...