Swagger Reflects the Short-Sightedness of Many API Industry Service Providers

Before I tell this tale, I want to make it clear I am not looking to disparage anyone who has worked at SmartBear, or still works there, and this is purely my opinion as the API Evangelist, and does not reflect my employers view in my role as Chief Evangelist for Postman. This post is in the spirit of good ol fashioned API Evangelist hellfire, brimstone, and truth telling, a hallmark of what made folks tune into API during the years between 2010 and 2020. I feel better after one of these tales, and I can’t help but feel that the world of APIs will potentially be a little less shady and fucked up as a result (but mostly it is about me).

This tale is about Swagger, a proprietary set of API tooling, which used to also be the name of an API specification. Swagger began its life as an open source project developed by Wordnik, a dictionary API. The goal was to provide a machine readable specification for HTTP APIs that could be used to generate documentation and SDKs. Then around 2015 Swagger, after the specification had taken off, the specification and tooling was purchased by SmartBear, who after some pressure from the community, agreed to put the specification in a foundation. However, at the last minute they decided that they would keep the very popular name Swagger, and rename the specification simply OpenAPI after putting into the Linux Foundation. Swagger was now a proprietary trademarked brand owned by SmartBrear, loosely applying to a mix of commercial and open source offerings within SmartBears control–not the open source specification that was put into the Linux Foundation.

Seven years later, Swagger still dominates search engines and many folks still think it is the specification, and do not understand the difference between Swagger and OpenAPI. I was involved in the whole journey, helping build up and popularize Swagger, as well as the transition from Swagger to OpenAPI, and now I am writing this story as my team continues to think critically about how we can help clean up this mess. I am part of the OpenAPI Initiative, and actively working to help educate the masses about the difference between Swagger 2.0 (old version), and OpenAPI 3x (new version), and the importance of migrating from the old to the new. However, most people don’t care about the spec, understand the politics behind, and aren’t aware of the need to migrate their tooling, services, and other implementations to support the latest specification. They also can’t tell the difference between SmartBear, Swagger, and OpenAPI, which is by design, and was the intent behind keeping the name, and branding the specification with such an obviously boring and hard to search for name.

I know first hand, that this was the intent. It was purely a business decision to recoup the money spent on the acquisition, which was apparently pretty costly due to others bidding for control, and this was deemed the best outcome. The fracture of the naming of the Swagger and OpenAPI specification has had a profound impact not he healthy and growth of the space right at a time where mainstream enterprise are waking up to the importance of API specifications, exponentially increasing the damage done each day. This is all in the name of business–when in reality, if the name had been kept part of the specification, there would have been even more money on the table for SmartBear, as well as all of the other service providers in the space who are selling their API wares, and supporting Swagger 2.0 and OpenAPI 3.x. For me, this behavior is just one of the more major examples of how business actually hurts itself, but also the wider sector, because of a lack of creativity, innovation, ethics, and an ability to actually deliver meaningful value to the space. This isn’t just SmartBear, this is something that can be seen in the practices of many API service providers.

I would put the Swagger / OpenAPI fragmentation up there with the scope of damage created by the Oracle vs. Google copyright case that played out between 2012 and 2021. Oracle had no idea of the damage they’d do with this case, and SmartBear had no idea of the damage they’d cause to the world of APIs with their name change. They don’t care either. Both companies try to compete, demand that they are relevant, and articulate that they care of developers, but it will be something that continues to bring both companies down, and contribute to their demise and irrelevance in coming years. All of the work we have to do as an industry is going to be exponentially harder due these types of plays for dominance in the sector. It isn’t limited to these two situations, and business leadership will continue to cut off their nose despite their face with short-sighted decisions like this. When you lack curiosity, creativity, and empathy, the real opportunity for generating revenue from the tools and API-driven services developers really need becomes much more elusive. Resulting in companies working real hard to acquire and litigate their way towards relevance, or what they perceive as dominance.

I guarantee that the shrapnel and negative impact introduced by the Swagger shit storm will be still be visible when I retire. Developers for generations will point out that machine readable specifications don’t work because of this industry example, when in reality it has nothing to do with the technical shortcomings of Swagger or OpenAPI, but the creative shortcomings of enterprises involved with the rise and fall of the specifications. I have learned this the hard way, but the best product, tooling, or standard doesn’t always win on its own merit in this space, and that doing APIs is more about the business and politics than it is ever about the technical details. However, the technical details make for a great way to distract developers while the are being screwed over. Developers just don’t see the wider world of business when it comes to what we do.Developers prioritize the technical details of how these platforms we are building work, while others who are less interested in technology, as well as the community of developers who believe in technology care more about fracturing, fragmenting, and disrupting sectors and being able to walk away with the lion share of the value that is on the table–even if it could be even greater if they just played by the rules.