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. 

Be sure to read the next Testing article: Postman 6.0 Introduces Workspaces to Improve Project Organization and Team Collaboration