Swagger: describir, producir, consumir y visualizar Servicios REST

(De nuevo gracias Luis :), este si que me ha convencido :P)

swagger es un framework (especificación e implementación) completo para describir, producir, consumir y visualizar Servicios REST.

El objetivo de Swagger es que la documentación del sistema se actualice conforme se actualice el Servicio, de modo que la documentación de los métodos, parámetros y modelo esté integrada en el código del Servicio permitiendo que las APIs estén siempre sincronizadas.

· Como Swagger es una especificación es independiente del lenguaje.

· Swagger ofrece implementaciones en Scala, Java y HTML5

· Swagger permite generar clientes Scala, Java, Javascript, Ruby, PHP y ActionScrip 3.

· Swagger soporta JSON y XML.

· Swagger UI framework permite a desarrolladores y usuarios interactuar con el API

Swagger se compone de varios módulos, entre ellos:

· Swagger UI es una aplicación HTML (+JS+CSS) que permiten generar documentación de un API Swagger.

Es en esencia una consola web completamente HTML que permite:

· listar operaciones:

· ejecutar operaciones

· Swagger Core define las anotaciones Java y la lógica requerida para generar un cliente o servidor Swagger. Incluye ejemplos en Java, Scala, con Play2 framework:

· Swagger node.js Servidor Swagger stand-alone escrito en Javascript con node.js

· Swagger Java Sample App Servidor Swagger stand-alone escrito en Java que demuestra como habilitar Swagger en tu API. El ejemplo se lanza directamente con:

> mvn package -Dlog4j.configuration=file:./conf/log4j.properties jetty:run

Abrimos Swagger UI local con esta url http://localhost:8002/api/resources.json

Si revisamos el código de la clase PetResource veo que Swagger ofrece anotaciones para documentar las operaciones (@ApiOperation), los errores (@ApiError) y los parámetros (@ApiParam)

Que en la consola web quedan:

Y cuando se produce error:

· Swagger CodeGen ofrece un motor de plantillas para generar código cliente en diferentes lenguajes parseando la declaración de recursos.

Por ejemplo en Javascript:

./bin/generate-js-lib.sh http://petstore.swagger.wordnik.com/api "" "" "generated-files"