Skip to main content

Swagger – documentando servicios

1 estrella2 estrellas3 estrellas4 estrellas5 estrellas (Ninguna valoración todavía)
Cargando…

Hace años que oímos hablar de los beneficios de SOA, de la reutilización de los servicios, de cómo permite ahorrar costes, etc. Imaginemos que ya estamos concienciados de esto y queremos entrar al detalle de compartir con nuestra organización dichos servicios.

Dependiendo de nuestro nivel de madurez de gobierno SOA podremos tener desde una Excel compartida (Oh my God) hasta un elaborado catálogo de servicios a disposición de todos los departamentos. En ambos casos nos encontraremos con una problemática común: ¿Cómo documentar nuestros servicios a nivel técnico?

reuseNos dejaron claro el mensaje: “reutilizar servicios es ahorrar pasta”. Pero claro, para que otros equipos utilicen nuestros servicios habrá que proporcionarles información técnica y funcional suficiente para que comprendan un servicio que no han desarrollado. Sí, hablamos de documentar protocolos, interfaces, DTOs, mensajes de error, etc., esas cosas que uno tiene dominado cuando es el desarrollador del servicio, pero no tanto cuando es el consumidor.

En este punto la solución más inmediata que nos rondará la cabeza será empezar a recopilar esta información de los servicios. Esta labor de redactar será llevadera al principio, aburrida al tercer documento y tediosa cuando se produzcan cambios en los servicios y haya que reescribir.

Aquí es donde entra en juego Swagger, un framework para documentar servicios REST a partir de nuestro código fuente. Para ello, haremos uso de diversas anotaciones, en nuestro caso para Java. Swagger ofrecerá mediante JSON o XML la documentación recogida con las anotaciones. Esta información puede utilizarse mediante una interfaz web que provee el framework o consumirla en bruto para que nuestra creatividad tenga vía libre.

Para ello vamos a estudiar un ejemplo. El primer paso será definir los objetos que vamos a usar en la interfaz de nuestro servicio. Para nuestro caso será tan fácil como modelar un bean que represente una tarjeta bancaria. Posteriormente implementaremos el api con los servicios RESTFULL del bean anterior.

Swagger0Con esto ya podemos levantar el servidor y conectarnos con la interfaz gráfica que provee el framework. Con ella podremos listar todos los servicios que hemos implementado e invocarlos de una forma cómoda.

Swagger1De esta forma logramos tener siempre una documentación actualizada con el código, además de la posibilidad de lanzar los servicios contra una sandbox o contra un entorno real de ejecución.

Swagger2

 

 

 

Pablo Pérez Aguiló

Consultor SOA. Graduado en Ingeniería del Software y Máster en Ingeniería Web por la UPM. Apasionado de las nuevas tecnologías, metodologías ágiles y la enseñanza.

Pablo Pérez Aguiló ha escrito 6 entradas


Pablo Pérez Aguiló

Consultor SOA. Graduado en Ingeniería del Software y Máster en Ingeniería Web por la UPM. Apasionado de las nuevas tecnologías, metodologías ágiles y la enseñanza.

Deja un comentario

Tu dirección de correo electrónico no será publicada. Los campos obligatorios están marcados con *