TODOS LOS CONCEPTOS AQUÍ EXPLICADOS ESTÁN REFLEJADOS EN ESTE REPOSITORIO

Algunos de los que me seguís sabréis que actualmente me encuentro trabajando en Seedtag. Aquí he tenido la suerte de descubrir esta maravilla de paquete llamado TSOA el cual nos va a permitir tener nuestra API documentada y actualizada casi por arte de magia.

TSOA nos va a permitir (mediante Decoradores y los tipos de Typescript) generar una documentacion con OpenAPI (Swagger de toda la vida para los mas viejos) de forma casi automatica y con muy poco esfuerzo en nuestro controladores.

Con los decoradores será capaz de documentar la estructura de nuestra API y con TS será capaz de comprender los datos que debemos recibir y devolver.

Instalación

Siguiendo su guía de getting started, podremos montar un 5 minutos un ejemplo básico. De esta parte destacaría principalmente:

• Instalar TSOA, Typescript, Express y Swagger.
• Instalar los tipos necesarios.
• Inicializar el proyecto typescript y añadir la configuración necesaria para TSOA.
• Crear un tipo custom con Typescript.
• Crear un controlador usando los mencionados decoradores:
  • @Route.
  • @Get.
  • @Path.
  • @Query.
  • @Post.
  • @Body.
• Crear un server con Express.
• Añadir la ruta para Swagger.
• Registrar las rutas con RegisterRoutes.

Después de toda esta configuración previa si lanzamos el server veremos que nos hemos conseguido nada y esto se debe a que TSOA es la encargada de generar las rutas y no nosotros.

Generación de Rutas

Bastaría con ejecutar el comando yarn run tsoa routes para que estas se generen pero como ya puedes estar pensando esta solución no es viable ya que en cada cambios deberíamos hacer una build, lo que no es lógico.

En la propia guía nos recomiendan, como paso intermedio, añadir los siguientes scripts en nuestro package.json

"scripts": {
 "build": "tsoa spec-and-routes && tsc",
 "start": "node build/src/server.js"
},

A mi personalmente esta opción no me gusta porque estamos teniendo que hacer la build de TS a JS y además deberemos para el server en cada cambio en nuestros controladores.

Live Reloading

Para conseguir la mejor experiencia de desarrollo posible vamos a apoyarnos en una serie de paquetes bastante conocidos dentro del ecosistema Node como son nodemon, ts-node y concurrently.

Por una parte usaremos nodemon y ts-node para poder ejecutar código TS directamente y concurrently para lanzar en paralelo varios comandos.

Únicamente necesitamos actualizar nuestros scripts en el package.json para incluir un nuevo comando dev y estaría todo listo:

"scripts": {
 "dev": "concurrently \"nodemon\" \"nodemon -x tsoa spec-and-routes\"",
 "build": "tsoa spec-and-routes && tsc",
 "start": "node build/src/server.js"
},

Ahora ya podremos levantar nuestro servidor y que esta actualice nuestra API en cada cambio.

Gestión de Errores

Ya para terminar me gustaría hablar sobre qué ocurre si algo falla en nuestro controlador ya que creo que es un tema bastante importante y del que tenemos que preocuparnos mucho a la hora de desarrollarlo.

La solucion que nos propone TSOA, como era de esperar ya que se apoya mucho por en Express, es hacer uso de un middelware especifico para errores donde controlemos cada caso y devolvamos el codigo HTTP oportuno en funcion del tipo de error que nos encontremos.