3 ms·

I just have to voice an opinion that swagger is not an API documentation tool. It might be a helpful tool, but it does not produce an API specification. An AP

I just have to voice an opinion that swagger is not an API documentation tool. It might be a helpful tool, but it does not produce an API specification. 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

BerislavLopac 6y ago
OpenAPI (not Swagger; that's the old name for the spec and the current name for the toolset) has all of the above functionalities. One important component is, to get the best benefit, it should be used for specification and not (just) documentation; in other words, you define the contract first and then base the various implementations (both server and client side) on it. Unfortunately there are not many tools that support that approach; I've tried to rectify that - for Python - with Pyotr [0]. [0] https://pyotr.readthedocs.io https://pyotr.readthedocs.io