{"API Evangelist"}

Generating Swagger Specs For The APIs Of The 700+ Companies That I Monitor

I'm about 1/3 of the way into generating Swagger specifications for the APIs at the 700+ companies that I monitor. I have the Swagger specs for almost 250 APIs so far, and have no idea how many I’ll have when I'm done (ha, will I ever be done), as the target is kind of ever moving. The only way to get to know an API better than having to create a Swagger spec for it, is to actually integrate with it.

Thankfully I’m not integrating with ALL of the APIs I monitor, but I do want to get more intimate with their API surface area, right up to actually having to integrate. There are four ways that I obtain a machine readable API definition for an API:

I would like to also add to the list, that I use API Blueprint, RAML, I/O Docs, and Apigee Explorer formats as well, but I do not. While these formats are out there, it is an understatement to say they are tucked away, and hidden. I’d venture to say the providers are actively assisting API providers in keeping buried, and hard to access—in my opinion each format should be front and center, accessible with a single click.

This is one of the reasons I use Swagger. If you look at Swagger UI docs, for each endpoint there is a RAW link which takes you directly to the machine readable API definition that drives it. Show me the equivalent on API Blueprint, RAML, Mashery, and Apigee API explorers, and interactive documentation and I’ll eat my words. I'm creating my own API stack for converting between all of these formats, but alas this doesn't help me in my API discovery process, because these formats aren't easy to find.

This disconnect, is one of the reasons there is so much fragmentation in API designs, and ultimately a lack of open tooling and services that support the entire API life-cycle—nobody wants to share their design patterns. Please help me document all the APIs in my API Stack, and if you know of an existing Swagger spec I don’t have, send my way, or publish to the Github repo. Also, if you are actively using an API, can you switch to using an APITools proxy and generate a Swagger spec that way, and also send my way, or publish to the Github repo.

I wish I could convince all y'all of the importance of this layer of the API space being not just machine readable, but also accessible. This is one reason why I’m hand rolling all of these API definitions myself, is because I’m just going to show you.