Eve-Swagger is a swagger.io extension for Eve powered RESTful APIs. It has been around for a while on GitHub but I never managed to officially release it. So rejoice! it is now available on PyPI.
But what is Swagger, and why is it useful to your RESTful API? With a Swagger-enabled API you can get interactive documentation, client SDK generation and discoverability, all for free. From Swagger website:
Swagger is a simple yet powerful representation of your RESTful API. With the largest ecosystem of API tooling on the planet, thousands of developers are supporting Swagger in almost every modern programming language and deployment environment. With a Swagger-enabled API, you get interactive documentation, client SDK generation and discoverability.
When Eve-Swagger is installed and properly configured your Eve API exposes
a special /api-docs endpoint which returns a 100% swagger-compliant JSON
response. This JSON can then be processed by the swagger tools like Swagger
UI and Swagger Editor. Here we can appreciate Swagger UI providing API
documentation out of the box (click to zoom):
Like most Eve extensions Eve-Swagger comes as a standard Flask Blueprint and, as such, using it is very simple:
Once the blueprint has been registered all you have to do is add a SWAGGER_INFO node to your settings. It maps to a swagger infoObject and contains some simple, human readable information. The extension will also scan your endpoint settings to figure out the API graph and document it. Of course, in order to not to clutter your launch script, you could (and probably should) set SWAGGER_INFO in your configuration file.
Installation is super easy:
This is just version 0.0.2 so many parts might still be moving, but you are encouraged to start using it right away. Also if you appreciate this extension please let me know by either starring it on GitHub or with a tweet or email, so I will know that I should really try hard and allocate more time to this project. As always, feel free to contribute via pull request!
If you want to get in touch, I am @nicolaiarocci on Twitter.