Desarrollar una API es duro. No sólo por el esfuerzo dedicado al diseño y la implementación, si no el tiempo que debe dedicarse a la documentación y a su mantenimiento para que los desarrolladores que vayan a usarla tengan claro su funcionamiento. Por eso, Swagger 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.
Es útil tanto a desarrolladores como a no desarrolladores, 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 no intenta resolver todos los problemas de las APIs, ni tampoco intenta decirnos como diseñar una API perfecta. Simplemente ofrece la creación de una documentación “vitaminada”, con sandbox incluido, de todos las llamadas que tengamos en la API. Trabajar con algo real que pueda hacer llamadas y comprobar los JSON de respuestas es mucho mejor que la documentación plana de una Wiki o PDF de texto que acaba quedando obsoleta y desfasada.
Ejemplo de documentación Swagger Demo
Más información | Swagger
Github | Swagger Core Wiki
