February 16, 2016 · swagger yaml REST API

A few impressions of Swagger - in combination with Flask

I developed a little REST interface a few days ago for a quick side project.
Originally I planned on using Flask and Sqlite to get the app going, but then I remembered I wanted to try Swagger for quite some time. So it was time to give it a shot.

What is Swagger?

According to Wikipedia Swagger is best described as:

Swagger is a specification and complete framework implementation for describing, producing, consuming, and visualizing RESTful web services.

It is a YAML based API definition scheme, that tries to keep your api, its documentation and the progress of your application in sync.
Addition to this scheme it provides useful tools for server and client generation that could consume your new API. Heck, there is even a live code editor on their pages, which is quite powerful and will recover in case you accidentally closed the browser tab. Neat.
But this applies to new APIs. Yet, Swagger would also be useful, if you have had an already existing API that you want to document. Just define paths, security roles and data ressources and you are set. Well, at least at it's basic levels. More details about the Swagger specification can be found on their site under specification.

First Impression

My first impression was very good. The editor and its examples help you understand quite quickly how it works. Unfortunately this can't be said for the overall documentation and specifications. They seem complete, but not very descriptive. Also they are a bit hard to navigate as the information is not always well structured and even feels incomplete at some points.

Still, Swagger got the job done. It didn't took me so much time to write my little API and it becomes a routine after a while, to work that YAML file.
Once you feel like you are done, it's time to let the tool generate a server application for Flask.

Flask and Swagger

In order to use Flask and Swagger together you need a library that does the heavy lifting between the two components. The Swagger Project bundled connextion with the server code. Connexion is the glue that turns Swagger definitions into valid Flask paths and resources, which is neat.
Connexion always comes with a UI to help you to manage and test your API. The UI let's you send requests with custom parameters. It's very easy to handle and much quicker than curl commands, if you haven't anything prepared for that.

The UI is usually located under https://<yourdomain>/<yourAPI_Url>/ui/

Verdict

So this was my first time with Swagger and such a definition language at all. Personally I see the charm of such a tool and the usefulness with APIs of any size. In fact I just remembered how cumbersome API work can be without such a handy tool.

I guess the biggest issues with Swagger is the handling of larger projects and scalability and that you have to rely on a translation layer between Swagger and which System you'll use it with, as those layers aren't handled by the swagger team. I assume that fast progress in the Swagger specification also means fast progress for the translation layers, but who knows since they are maintained by third parties.

Other than that, it is a great little tool,that makes Api design much more fun.
Check out their website

  • LinkedIn
  • Tumblr
  • Reddit
  • Google+
  • Pinterest
  • Pocket
Comments powered by Disqus