Wednesday, January 7, 2015

Swagger is great but integrating documentation with code seems like a bad idea.

Swagger is a way of documenting REST API's.  It's useful and clever.

However much of the ecosystem seems oriented toward integrating Swagger documentation directly into the API source code.

This seems like a bad idea.  I want my REST API source to be minimalistic and simple.  The less code, the fewer bugs.  Integrating Swagger directly into the source code seems to significantly increase the code size and therefore the potential number of bugs.

For large projects this would seem to lead to a significant increase in code complexity.

A further issue is that the Swagger spec is being updated over time and keeping your source code in sync with Swagger seems less practical than keeping a static Swagger spec for your API updated.

Better to just make a static Swagger file that documents the API.  I can't see that this approach is significantly less functional than integrating Swagger into the code.

No comments:

Post a Comment