New Tool From SmartBear Reverse Engineers API Calls Into OpenAPI Definitions

Somerville-based SmartBear, a company with a heritage in API testing, has added another cloud-based solution to its portfolio of API tools. Based on ProgrammableWeb’s cursory look at the tool, one of the more interesting things that it can do is turn an API call (or collection of calls) into an OpenAPI Specification-based (OAS) definition. 

The solution however, is a good example of how the company sows confusion in the industry when it comes to the current state API specifications. The company’s press release also claims that the tool is free. But in ProgrammableWeb’s tests, we discovered that's it's more of a freemium model rather than a capability that was free in totality. At least one feature we found, an important one at that, is only available to paid users.

First, in terms of the cursory look, Swagger Inspector opens to a web page that has many of the elements found in what are often called “API Consoles”; a feature found in some API developer portals that allows developers and other visitors to construct an API call out of the various parts that typically go together to form one; an HTTP verb like GET or POST, an endpoint, authentication parameters (eg: Oauth), other HTTP headers, and any query parameters. With this form, users of Swagger Inspector can input an API call by hand or they have the choice of auto-generating calls from an existing OAS definition.

This choice of starting points speaks to the flexibility of Swagger Inspector as a testing tool. With Swagger Inspector, you can validate an existing OAS API definition by ensuring the legitimacy of the API calls it auto-generates. Going the other direction, you can hand-craft an API call that Swagger Inspector can turn into an OAS definition which in turn can be used as an input to other testing solutions.  

Swagger Inspector opens to a form from which the user can hand-craft an API call

Given how the YouTube Data API is fresh in our minds here at ProgrammableWeb because of a series of Hello World tutorials we’re publishing, we decided to hand-craft an API call to that API to see what happens next. As can be seen from the screenshot below, if the API call is a valid call, Swagger Inspector displays the response to that call. Additionally, it adds the call to your history of calls (lower-right hand corner).  

The Swagger Inspector main page after an API call has been made.

Since it’s impossible to write one API call that exercises an API’s every possible option and resource, Swagger Inspector allows you to click a checkbox next to one or more of your historical calls and then add all of the checked calls to a collection that is given the name of your choosing. We made a couple of different API calls and named our collection "YouTube API.”

Finally, whether you’re viewing the main screen where you can check one or more of the historical API calls, or you’re viewing all of the API calls that you added to a collection, you can generate an API definition from the API calls that are checked. 

For example, if you click the checkbox next to just one of your historical API calls, it can generate an API definition (a rather short one) that’s based on that one call alone. But if you click the checkboxes next to multiple different API calls, it will sort through all of them and generate a single definition that represents all of them combined. It’s an impressive feature. 

Unfortunately, in releasing this tool the way it has released it, SmartBear is continuing a pattern that we’ve observed over the last year whereby it is confusing the API market about the industry’s transition to the OpenAPI Specification as the widely accepted standard for defining APIs. 

Backed by the Linux Foundation, the OpenAPI Specification is the successor to an open source project known as Swagger.  SmartBear acquired the project in 2015 and was one of the companies that spearheaded Swagger’s evolution into the OpenAPI Specification. The company’s collateral materials do in fact make reference to its support for OAS. For example, in a video announcement about Swagger Inspector,  SmartBear product manager Shannon Wallace talks about how you can create API definitions based on the OpenAPI Specification. She refers to OAS as “the world’s leading API standard.”

However, not only is Swagger Inspector not called "OAS Inspector" as it could have been, there are several visual queues in the service that continue to promulgate Swagger as the defacto standard. For example, in the first screenshot shown above, the field at the top of the screenshot says GET “any HTTP resource or the URL of a Swagger / WSDL definition.”

Then, as shown in the screenshot below, at the moment a user goes to generate an API definition as described in the process above, you are presented with a dialog box titled “Generate Swagger Definition” instead of “Generate OAS Definition.”  It goes on to say “Your generated Swagger definition will be opened in SwaggerHub.”

Once this definition is created in SwaggerHub, the user is presented with another dialog box with the same title. But this time, the text says “You have successfully generated your Swagger definition” (see partial screenshot below).  

Then, once the definition is created, the resulting definition is identified as a Swagger 2.0 definition instead of an OAS definition as shown below. In fact, in our tests, we didn’t see any references to the OpenAPI Specification in the tool. Just Swagger. It doesn’t mean they’re not in there somewhere. We just didn’t see them. The importance of this should not be underestimated. On the one hand, SmartBear waves the OAS flag in its promotional materials to say it conforms with industry standards. But on the other, SmartBear is not doing the emergent OAS standard (which it donated to the Linux Foundation) any favors by undermining it with continued references to Swagger-based definitions in its newest tools.

Swagger Inspector's resulting API definitions are classfied as Swagger 2.0 instead of OpenAPI Specification

Finally, as mentioned earlier, when the tool generates an API specification, it actually does so from within another one of SmartBear’s tools; SwaggerHub. So, in essence, the generation of the API definition — an advertised feature of Swagger Inspector — relies on another tool to finish the job. Technologically speaking, the product didn’t have to be designed this way. In fact, Swagger Inspector could probably have done it using an API call to SwaggerHub without ever leaving the Swagger Inspector interface. But once in SwaggerHub, you have the option of keeping the definition public (the default) or making it private. The public option is free which means other users of SwaggerHub can see it. But if you want to keep your API definition private (at least until you’ve finished your design), you’re confronted with a message that making it private is strictly a paid option. 

David Berlind is the editor-in-chief of You can reach him at Connect to David on Twitter at @dberlind or on LinkedIn, put him in a Google+ circle, or friend him on Facebook.

Comments (3)


Hi David,

Thank you for writing about Swagger Inspector, and I'm glad you find the create definition feature to be a good one! I wholeheartedly agree; it's my favorite feature of the tool. You're right about our verbiage, and I'm keenly aware of the word "Swagger" showing up in Inspector, and other products, when we actually mean "OAS" or OpenAPI Definition. These text changes are items we have high in our list of to-do's, and unfortunately didn't get done in time for the official Swagger Inspector release. In hindsight, they should have. 

I appreciate the feedback. Those text changes are forthcoming. We agree that being clear in our verbiage and messaging is important for the clarity of the community.

All the best, 

Shannon Wallace


Hi Shannon, that's great to hear that SmartBear will be changing its verbiage in this solution. Can the industry assume this will be true for verbiage that appears elsewhere? For example, on this page on SmartBear's web site about the definition editor, it says the following:

  • "We’ll keep an eye on your API definition as you build and immediately give you the information you need to ensure your definition meets the Swagger specification."

Another example is how, on this page about the features of SwaggerHub, it says:

  • "At its core, SwaggerHub is based on the Swagger principles of open, integrated technologies."
  • "Browse our list of Swagger-based APIs and explore them using our interactive documentation."

Over here on this SwaggerHub overview page, there's a passage that says the following:

  • "Easily push your Swagger definition to any service you define with the Webhooks Integration." 

These and other pages are noticeably devoid of any mention of the Open API Specification. So, perhaps you can see why it looks more like a pattern than an anomaly.  

I think the industry looks forward to a rapid purge of such references to "Swagger" in favor of "OAS" so that all supporters of the OAS ecosystem can equally benefit from the avoidance of any confusion.