Documentar Servicios REST

Swagger: Documentar Servicios REST

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"

Saludos
Renzo Huertas.