A few years ago I was working on an API that my client was going to make available to some of their clients. I used Swagger, which I’d heard about from a Gluecon presentation.
I was unimpressed. I recall having difficulty getting the online tool to work and the documentation generated was poor. This could very well have been user error or my misunderstanding of the sweet spot of the tool, but for whatever reason it wasn’t a fit for the problem.
Fast forward a few years and I was talking to a company about a position. They were planning to use Swagger to generate their API SDKs. They had an API which was crucial to their business and were currently supporting a large number of SDKs on a bespoke basis. I reviewed the documentation of Swagger and downloaded the 2.3 version. I was very quickly able to generate a number of client and server stubs using the codegen project. They have a long list of supported languages, but I quickly generated ruby, csharp and perl client bindings and a simple rails5 and spring server. I didn’t push these through to production and I’m sure that if I had I’d have learned about the rough edges (it’s always nice to check out Stack Overflow for rough edges for any technology–here’s questions for swagger). Regardless, the ability to take a simple JSON configuration file and create API front ends and backends in minutes was quite impressive.
Note that the codegen tools are all in java, so if leveraging that technology gives you the willies, you might want to look around for another solution. Note also that Swagger has now been moved to the OpenAPI project (as of version 2.0 of Swagger). If you want to know more about that, here’s the blog post announcing that move. Here’s a look at features of the next version.
If you are developing an API first company (and there are good reasons to be that), I’d recommend taking a long hard look at Swagger. The speed of adding SDK support as well as the community around this tooling look to be huge advantages.