Interactive API Documentation: the New API Console for Developers

One of the consistent concerns of API providers is the experience they provide to their users and how they can make their API documentation user friendly, interactive, intuitive and clear.

At 3scale when we are asked how to make it faster and easier for developer to interact with an API without hesitation we say “Swagger”

Swagger is a powerful Open Source Framework enabling API documentation and exploration in a friendly and easy way. It lets developers learn, play, test and debug every single element of your API and makes their life simpler when it comes to developing apps. Swagger is an improved version of an API Console.

You can download the Swagger framework from http://swagger.wordnik.com/.

Swagger Framework Overview

Swagger is language-agnostic. However Wordnik (the creator of the Interactive API documentation) has released Swagger implementations in Scala, Java, and HTML5 and client generators are currently available for Scala, Java, Javascript, Ruby, PHP, and Actionscript 3. Wordnik says that more client support is underway.

Swagger is an improvement on existing specs like WSDL 2.0 and WADL which must support legacy systems in order to be generally accepted.

As Kin Lane mentioned in his analysis of Swagger, there are 3 main benefits for API owners coming from adopting Swagger:

  • Automated, consistent generation of clean, beautiful, interactive API documentation
  • Generation of client code and SDK in multiple languages
  • Feeding into an industry wide API discovery language that both developers and non-developers can use

If you would like to know how Swagger can be used with 3scale’s API Management Platform contact us at info@3scale.net