Swagger se ha convertido en una herramienta imprescindible a la hora de documentar un proyecto Rest que todo buen Desarrollador Backend debe conocer. En este artículo nos centraremos en las herramientas libres de Swagger.

Para poner en marcha estas herramientas necesitaremos tener instalado Docker y Docker Compose. Se puede instalar entro otros en Linux, MacOSX, incluso en Windows, pero esta última opción es la que menos te recomiendo, por lo complicado de su instalación debido a Hyper V, y porque dejarás de poder arrancar máquinas virtuales tanto de VirtualBox como de Vmware de manera normal.

Para poner manejar los contenedores descárgate o clona el repositorio https://github.com/pepesan/swagger-docker-compose los fichero mínimos.

Una vez bajados debería bastar con ejecutar:

docker-compose up -d

Para ver si están levantados los contenedores:

docker-compose ps

Para parar los contendores:

docker-compose down

Si todo va correcto deberías poder acceder a la URL: http://localhost:8081/ y deberías encontrar el editor de swagger.

A partir de este momento ya puede empezar a jugar con el editor para cambiar la especificación y ver cómo queda la documentación generada.

Luego podrás exportar el fichero en JSON o YAML desde el menú File, generar clientes o servidores basados esa especificación desde los menús Generate Client y Generate Server respectivamente.

Si te interesan estos temas te recomiendo que visites el blog o el podcast de república web, episodio 108 donde comentamos esta herramienta y otros temas muy interesantes.