Visualizing Swagger API documentation

12 Jan 2018

by Petteri Vainikka

Why our association with Swagger makes sense for us, and for you.

We like to give added value, and make processes as simple and beneficial as possible. And that’s why we work with Swagger.

To show off the functionality of our Swagger add-ons, we’ve imported two well-known APIs. You can explore them in Ardoq without signing up by clicking below:

What is Swagger?

Swagger is a simple yet powerful metadata format that makes it easy to generate documentation of RESTful APIs. With implementations in many popular languages/frameworks, and a growing set of tools to support it, Swagger has become a popular way to generate API-documentation.

The reasons

Since Swagger already offers automatically generated documentation as well as a nice UI, it’s fair to consider why exactly we decided to make this add-on in the first place.

One obvious reason is that it’s a simple way to test our new add-on capability, since Swagger provides a simple-to-parse JSON-format. If you’re a developer, I’m sure you can appreciate the appeal of having others do the hard work.

A more appropriate reason is that Ardoq can enhance any API-documentation by giving you better insights into how the API works, and also its dependencies within your organization.

The-benefits

The benefits

From a consumer perspective, we believe Ardoq can make Swagger documentation easier to understand by providing explorable visualizations. Give it a try, and tell us what you think. This example is based on this Swagger endpoint, with the corresponding Swagger UI available here.

Automatically generated API documentation is great, but you often want to combine it with other documentation, such as guides and how-tos. This is especially true if you are providing a public API. In Ardoq, you can easily combine manually and automatically generated documentation, as well as handle versioning, publishing, and access control.

As an API provider, you care about a lot more than just the public side of an API. You most likely have to manage dependencies to backend systems and infrastructure, handle API-versioning, ensure you deliver on SLA: the list goes on. We often like to think of these things as separate from the actual API documentation, but having the option to include these dependencies and provide an at-a-glance overview of them can be really powerful.

Sound interesting? Take a look at this video explaining how Ardoq does it, or sign up for a free 30-day trial and try it for yourself.

What’s next?

We are excited about the potential of combining manual and automated documentation. If you have any feedback or ideas on other technologies we can automate, please drop us a line - we’d love to hear from you.

Finally, a big thanks to the folks at Reverb for their excellent work on Swagger!

New Call-to-action