Tooling Review: Swagger Inspector

Testing is often considered to be a secondary consideration at the end of the development lifecycle. The common thought is that APIs are tested after they are built, and that any issues found should be addressed during these later stages. While this is certainly a method that can deliver a finished product, utilizing testing in such a manner is missing some major benefits of earlier testing. All that is needed to reap these benefits is an effective, powerful tool for early inspection, testing, and perhaps even some additional features to round out the offering.

Enter Swagger Inspector. Inspector is a new offering in Swagger Hub that promises to be the “easiest way to test and auto-generate OpenAPI documentation for any API”. A new offering in the Swagger ecosystem, the tool has seen extensive beta testing, and is now at a stage that deserves some attention.

Today, we’re going to discuss Inspector, and identify some solid points where it truly shines, as well as some caveats that should be considered prior to adoption.

API Testing in the Cloud

One major benefit of Inspector is that it is cloud centric. The way Inspector functions allows the user to test and validate APIs in the cloud, rather than requiring the user to download a desktop application or install a plugin or other browser-based solution. This is very beneficial, allowing on-demand, any-location testing.

While this has its obvious benefits in terms of user experience, the shift to the cloud is actually part of a greater sea change in how such applications are handled in the industry as a whole. The cloud is no longer a “brand new” technology – while it has far to go, the cloud has become key to many business functions, and is near ubiquitous for modern software development teams. Everything from email to document sharing, from development to documentation, has some option in the cloud to facilitate collaborative efforts for a greater final product.

Simply put, as APIs and the tech industry in general shifts more towards a cloud-based approach, API testing will likewise see this shift. When the majority of new offerings are in the cloud, it’s very hard to justify a non-cloud solution. As such, Inspector offers a great deal in a very attractive cloud setting.

Generate OpenAPI Documentation

One of the greatest selling points of the Inspector solution is the ability for automatic generation of OpenAPI definitions from any service that the Inspector tests. This documentation, once generated, can then be ported to SwaggerHub. OpenAPI has many benefits in and of itself, but for many providers, the idea of switching over to a new solution for an already existing implementation is daunting at best, and in many cases, precludes the service from being viable.

Inspector consuming the Petstore Open API definition

Inspector gets around this by entirely automating the process, and storing it on a collaborative hub. This means that Inspector is not just an inspection tool, but in fact is an Inspector tool that offers a greater amount of output in a more dynamic, usable form than one might expect. This puts it heads and shoulders above other offerings which simply test. That being said, not everyone wants to use the OpenAPI specification. In these cases, you can choose whether or not to utilize the tool based on your organization’s needs.

Leveraging this solution to create documentation also offers a unifying experience. Many have “bought in” to the Swagger experience, and given that Inspector is itself part of the Swagger ecosystem, utilizing it in Swagger implementations just makes sense. While this could in itself be a selling point on its own, when paired with the OpenAPI Documentation generation, a truly unified system and workflow is presented and must be considered for all of its benefits.

Test Almost Anything

Inspector is designed specifically to allow for testing across a wide range of APIs, including, according to its own documentation materials, REST, SOAP, and GraphQL. This open base for support means that Inspector isn’t as limiting as other testing solutions, the bulk of which are often designed solely for the given framework, specification, language, or architectural choice.

By utilizing this type of approach, Inspector is positioning itself to be a one-stop shop for API testing and definition generation. This is very much a needed offering in the space, and presents a shift towards a unified approach rather than a segmented one.

A Testing Tool for Development Guidance

Inspector offers a unique unified experience that might be missed on first glance. It’s tempting to consider Inspector to be no more than a testing tool, but it is more multi-purposed than meets the eye. In other words, Inspector is poised as a testing and generation solution, and as such, considering it simply to be a quality assurance or bug hunting solution is missing the point.

Inspector provides ample generation during testing, and for this reason, it should actually be considered a tool that aids in development. Once integrated into a development lifecycle, Inspector can be used to generate OpenAPI documentation as a discrete secondary function, independent of its primary testing function. Documentation generation throughout development is key to finding not only issues with the code base, but issues in the approach an organization takes to API architecture.

Accordingly, Inspector offers a great tool for early testing that allows the solving of problems while preventing their propagation. If the team intends on creating documentation – and truthfully, it should – then it makes more sense to do it correctly and to do is as early in the process as possible to leverage these benefits.

Design and Experience

While this is not necessarily a technical point, Swagger Inspector is simply great to use. The interface is extremely clean, everything is clearly labeled, and the design of the interface and web elements themselves are in line with the rest of the Swagger ecosystem offerings. In not so many words, Inspector is pretty.

Inspector’s light theme

Design is akin to a splint. Small and minor, you’d never notice the splinter of wood in a woodpile, on a table, or even on your clothes. If, however, that splinter were to find its way into your thumb, it would be obvious, glaring, and annoying. Design functions exactly the same way – when the design of your user interface is good, you’re not very likely to notice it. When it is bad, however, it not only interferes with use and the user experience, it can result in a fundamental breakdown of the user workflow.

Inspector’s interface is so good that it’s delightful to use – and that is a major positive point that cannot be overvalued.

Compounding Use with SwaggerHub

One major selling point for Inspector is the fact that it ties directly in SwaggerHub. SwaggerHub is an API design platform that enables collaborative team design. The platform itself offers a large amount of integrations, services, functions, and more that makes it in itself a product worthy of consideration.

The fact that Inspector ties directly into SwaggerHub makes this not just a product for consideration, but an ecosystem to consider in general. While Swagger is not always the correct answer to every single problem, and SwaggerHub is thus similarly not the correct answer in every single case, the ecosystem as a whole is a very good option for many teams. The fact that Inspector ties into SwaggerHub should be considered a leveraging point that makes the sum of the products greater than the whole.

It’s Free

One thing to note is that Inspector is free, and according to the SmartBear marketing material, their intention is to keep it that way. While being free does not necessarily make the implementation the best choice alone, it certainly does sweeten the deal. A free option makes for easier cost-benefit analysis, offering a great amount of functionality for a very low investment in time and energy.

The proof is in the pudding, however – and only the future will be able to show whether or not the free aspect is truly a selling point. Whether this free version is limited in the future, whether a paid variety is offered as a premium variant, and whether the general SmartBear ethos and approach shifts, will determine whether or not this is a “cherry on top” or a secondary consideration.

Consumer Enabling

Perhaps the strongest selling point of Inspector is the fact that it enables more complete and effective consumption of an API. The end user is not always going to have access to your documentation, and even if they do, it may not function in the way that is required or necessary. In these cases, users often find themselves left to their own means to discover the secrets of your API, which can lead to disastrous exposures and breaking functionality.

When using Inspector, you fix this in two ways. First, by utilizing the OpenAPI Specification documentation generation, you’re creating a standardized, easy to navigate set of documentation for your users that negates many of the issues noted above. More to the point, as a user, utilizing Inspector gives you an insight into the API in question, and exposes much more information than basic a-b testing through trial and error.

Inspector allows for consumption of the API in a more interactive, beneficial manner.

Caveat Emptor

All of this being said, there are certain cases in which Inspector, or more specifically the OpenAPI documentation it generates, is not the best choice. Two particular instances that come to mind are as follows.

  • Private APIs, especially those who do not intend themselves for public consumption, may choose not to utilize Inspector due to the nature of its OpenAPI and SwaggerHub integrations. Because these APIs are designed to be consumed by specific users, who are typically trained in the API itself, these materials are not appropriate in such cases.
  • Likewise, internal APIs that must adhere to the traditional waterfall development lifecycle, where testing happens at a specific stage, may not benefit from everything that Inspector has to offer. While they can still use Inspector at the late stage, the fact is that it would be akin to using a jackhammer to remove a hangnail – technically doable, but a bit overkill to say the least.

Conclusion

Inspector is a great option for many teams, given that the team sees benefit in both the OpenAPI materials it offers and the nature of its testing approach. While not every API will benefit from its adoption, or for that matter the adoption of OpenAPI or the SwaggerHub, many APIs could, and for this reason alone, it bears some consideration as a possible solution.

That being said, each API is individual in its requirements: the systems it needs to function, its approach to testing, and even its general design ethos. Accordingly, Inspector may be your ideal tool – assuming, of course, that your problem is that which it intends to solve.