IBM Watson API Today we are happy to announce the general availability of our new Swagger add-on. To show off the functionality, we’ve imported two well-known APIs. You can explore them in Ardoq without signing up by clicking below:

Last week we wrote about our plans to make it easier to get started documenting in Ardoq. This launch is the first in a series of new add-ons we are developing to help you kick-start your project. The roadmap so far includes add-ons for C#, Java, Node.JS and Clojure, as well as the possibility to develop your custom add-ons.

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.

Why would you want to use this?

Since Swagger already offers automatically generated documentation as well as a nice UI, it’s fair to ask why 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 (at least that’s what we’re telling our sales department) is that Ardoq can enhance any API-documentation by giving you better insights into how the API works, and also it’s dependencies within your organization.

Benefits of combining Ardoq with Swagger

From a consumer perspective, we believe Ardoq can make Swagger documentation easier to understand by providing explorable visualizations. Instead of me trying to describe how (I’ve tried and failed at this before), 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.

Swagger_Window

Automatically generated API-documentation is great, but you often want to combine it with other documentation like getting-started guides and how-to’s. 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, make sure 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 trial and try it yourself.

What’s next?

The plan is to launch more add-ons in the coming weeks. First up is the .NET add-on. It makes it possible to visualize dependencies automatically by uploading a .NET-based .DLL assemblies.

We are really excited about the potential of combining manual and automated documentation. If you have any feedback or ideas on other technologies we can automate, place drop us a line in the comments – we would love to hear from you.

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


Want to visualize your Swagger documentation in Ardoq? Sign up or request a live demo from one of our team members!

Try it for yourself

Ardoq is free for small teams!