miércoles, 25 de junio de 2014

Documetando APIs Rest con Swagger


Te imaginas un javadoc de tus servicios REST? Swagger es eso y mucho más dado que es una herramienta extremadamente útil para describir, producir, consumir y visualizar APIs RESTful. El principal objetivo de este framework es enganchar el sistema de documentación con el código del servidor para que esté sincronizado a cada cambio. Casi documentamos al mismo tiempo que creamos la implementación.

Swagger está desarrollado de tal modo que podemos usar Scala, Java, Javascript, Ruby, PHP o ActionScript para generar toda la documentación y su sandbox correspondiente. Además, existen distintos módulos para enganchar a nuestros proyecto Node.js, Grails, Scala Play, Spring MVC, Symfony o Ruby, entre otros muchos.

Los usuarios de las APIS también son beneficiados ya que proporciona una interfaz visual a modo de sandbox donde podemos testear la llamadas del API, además de consultar su documentación. Podéis echar un vistazo a un ejemplo de la web que genera Swagger a partir del código de nuestra API con los métodos, parámetros y modelos de JSON que devuelve.

Swagger es perfecto para tener la documentación de nuestras APIs a punto y brindarle un servicio más a los clientes con ejemplos.

The Swagger™ Specification: https://github.com/wordnik/swagger-spec
Swagger™ Demo: http://petstore.swagger.wordnik.com/
Downloads: https://github.com/wordnik/swagger-core/wiki/Downloads