[^1]: https://swagger.io/docs/
* Preferred way of doing X
* X domain uses these tables and works like this
* This is what X feature does and here's what it looks like
Most of us work in the single large codebase, and we don't have a good separation of responsibility between the pieces yet (it's a work in progress) so for now I mostly want to document what stuff exists rather than formal API documentation.
An API specification:
- must be diff'able with any previous version
- must have a version number
- must specify every parameter, it's range, whether it's mandatory or not, list all possible values for enumerated types, etc.
So if you use swagger, you won't be able to:
- review changes needed in your part of the system before the code is published (even in a development environment)
- analyze impact of the changes
- understand the dependencies
Unfortunately there are not many tools that support that approach; I've tried to rectify that - for Python - with Pyotr [0].