Swagger: qué es y cómo utilizarlo

Swagger se ha convertido en una herramienta imprescindible para el desarrollo moderno y basado en API REST y a la que podamos sacar partido en muchas tareas: desde el diseño a la documentación o la generación de código. 

¿Qué es Swagger?

Swagger es el paraguas sobre el que se agrupan una serie de herramientas de código abierto pensadas para el desarrollo de proyectos basados en API REST. Entre otras, ofrece utilidades que permiten diseñar, construir, documentar e incluso consumir servicios web.

Dentro de estas herramientas la utilidad principal consiste en facilitar la documentación de las API, algo totalmente imprescindible para mejorar la comunicación entre los equipos de desarrollo.

Relación entre Swagger, OpenAPI y RESTful API

Dentro del ecosistema de Swagger encontramos dos productos relacionados que vamos a distinguir. Es importante aclararlo, ya que a veces puede resultar un poco confuso para las personas que comienzan con estas tecnologías.

¿Qué es OpenAPI y cómo evolucionó a partir de Swagger?

Como quizás sepas, Swagger comenzó siendo un proyecto dedicado a la documentación de APIs. Sin embargo, debido a su popularidad, poco a poco se fue convirtiendo prácticamente en un estándar en la industria, por lo que se hicieron movimientos para separar lo que son las especificaciones de documentación de las propias herramientas.

Así es como nació OpenAPI, que no es más que la especificación que se había definido en Swagger. Actualmente OpenAPI es responsabilidad de la Linux Foundation, mientras que Swagger es un conjunto de herramientas que implementa y da soporte a esta especificación.

Cómo Swagger documenta y define API RESTful

Swagger permite definir todos los aspectos de la documentación de una API RESTful, tales como endpoints, métodos HTTP, parámetros, respuestas, esquemas y códigos de estado, a través de archivos de texto, que pueden estar en formato YAML o JSON.

Esta definición se puede usar por medio de múltiples herramientas para generar la documentación de las API pero también para generar pruebas o producir código de cliente para consumir las API, entre otras cosas.

Diferencias entre Swagger y OpenAPI: ¿son lo mismo?

Por tanto, aunque Swagger y OpenAPI comparten un mismo origen actualmente son cosas distintas. Si bien están muy relacionadas entre sí, en realidad OpenAPI es simplemente una especificación, mientras que Swagger continúa su camino aportando un conjunto de herramientas que permiten trabajar con esa especificación.

Ambas resultan esenciales en el desarrollo de proyectos modernos de servicios web que implementan el modelo RESTful API.

Por qué Swagger y OpenAPI son clave en arquitecturas REST

En el desarrollo de servicios web es fundamental aportar una documentación que sirva para definir cómo se deben usar esos servicios, ya sea por los clientes frontend, o a la hora de orquestarlos dentro de arquitecturas basadas en microservicios.

Ya que tenemos la necesidad de aportar documentación en los proyectos de arquitecturas REST, la mejor manera de hacerlo es mediante estándares bien conocidos en la industria como OpenAPI.

¿Para qué se utiliza Swagger en el desarrollo de API?

Ahora vamos a ver una serie de casos de uso donde Swagger nos aporta numerosas utilidades en el ámbito del desarrollo de API REST.

Documentación interactiva de endpoints

Realizando la documentación de las API con Swagger seremos capaces de generar sitios completos de documentación de los endpoints, donde se puede conocer todos los detalles de implementación de los servicios web.

Incluso estos sitios de documentación son completamente interactivos, por lo que los desarrolladores pueden usarlos para probar los proyectos y analizar el uso y resultado de cada uno de los endpoints del API.

Validación y pruebas automáticas de servicios

Swagger también nos ofrece herramientas con las que es posible realizar peticiones y obtener respuestas del API. Esto nos permite validar y hacer pruebas automáticas de los servicios web durante el desarrollo.

Generación de código cliente y servidor

Aunque inicialmente Swagger es una herramienta pensada para la documentación, en la práctica podemos invertir el flujo y comenzar documentando el API, para luego generar a partir de la documentación el código de servidor para implementarla.

Al mismo tiempo también esta misma documentación puede servirnos para generar el código de los clientes que deberán consumir el API. Todo ello a través de Swagger Codegen.

Principales componentes del ecosistema Swagger

Para conseguir ofrecer todos estos servicios Swagger nos ofrece diversos componentes que vamos a resumir en los próximos puntos.

Swagger Editor

Se trata de un editor con el que podemos escribir y mantener definiciones OpenAPI, en los lenguajes de definición soportados, YAML o  JSON. Este editor nos aporta algunas ayudas a la hora de generar el código como validación en tiempo real y vista previa de la documentación generada.

Swagger UI

Es una de las principales herramientas ofrecidas por Swagger, o al menos de las más usadas. Consiste en un generador del sitio web de la documentación del API, que además es completamente interactivo.

Gracias a Swagger UI los desarrolladores pueden conocer todos los detalles de implementación de un API, revisar los endpoints, ver tipos de respuestas con sus ejemplos  y realizar peticiones directamente desde la interfaz web.

Swagger Codegen

Codegen es la herramienta de Swagger que permite generar automáticamente el código cliente y servidor a partir de una definición OpenAPI. Codegen es una herramienta compatible con numerosos lenguajes y frameworks y se usa principalmente para acelerar el desarrollo de APIs y sus integraciones.

Ventajas de usar Swagger en entornos de desarrollo ágil

Como has podido comprobar, todas las herramientas de Swagger están encaminadas a la mejora de los flujos de desarrollo, por lo que son ideales para proyectos API REST. Algunas de las ventajas principales que puedes obtener con su aplicación son las siguientes.

Mejora la colaboración entre backend y frontend

Gracias a la documentación del API y los sitios interactivos de documentación, los equipos de desarrollo backend y frontend tienen mucho más fácil la colaboración.

Además, siendo la documentación extensa y detallada los equipos frontend podrán trabajar sin dudas, haciendo posible incluso el desarrollo de las partes del cliente de manera paralela al desarrollo del propio backend del servicio web.

Facilita la escalabilidad y el mantenimiento de API

Documentar cada detalle del API es fundamental para el mantenimiento, lo que impacta también positivamente en la escalabilidad del proyecto. Gracias a ello es más fácil corregir inconsistencias y aportar coherencia al proyecto.

Además, cuando un nuevo desarrollador se incorpora al proyecto, le resulta muy sencillo entenderlo ya que toda la documentación está desarrollada siguiendo un mismo patrón, que probablemente conozca de antemano.

Reducción de errores en la integración

Gracias al minucioso detalle que podemos aportar en la documentación también conseguimos reducir de manera sensible la introducción de errores en la integración del servicio web, cuando desarrollamos el código cliente.

Cómo empezar a usar Swagger paso a paso

Podemos usar Swagger en multitud de lenguajes y frameworks de desarrollo. Esto hace que los pasos concretos para poder empezar a trabajar puedan tener diferencias sensibles a la hora de aterrizarlos en tu stack de tecnologías. No obstante, vamos a ver algunas guías esenciales para poder ayudarte a entender los primeros pasos usando las herramientas propuestas por Swagger.

Instalación básica del Swagger Editor

Si queremos empezar por el diseño de nuestra API REST una buena alternativa es utilizar Swagger Editor. Si lo deseas, esta herramienta la puedes usar directamente desde su sitio web:  https://editor.swagger.io/

Esa es una buena alternativa para probarla, pero también puedes usar Swagger Editor instalando el programa en tu ordenador. Solo que a día de hoy no existen ejecutables como en otros editores del estilo de VSCode, en realidad es una aplicación web que tienes desplegar en tu ordenador.

Es por ello que lo más cómodo es usar Docker, que ya te da la imagen con todo listo para empezar a trabajar. Lo puedes hacer cómodamente con estos comandos:

docker pull docker.swagger.io/swaggerapi/swagger-editor

docker run -d -p 80:8080 docker.swagger.io/swaggerapi/swagger-editor

Puedes encontrar otras guías y alternativas para la instalación en la página del proyecto Swagger Editor en GitHub.

Crear tu primera especificación OpenAPI

Una vez abierto el editor puedes empezar a trabajar con la especificación de OpenAPI para la definición del servicio web. Aquí sería ideal estudiar la especificación, así como la sintaxis con la que debes trabajar para poder definir el servicio.

Si quieres ver varios ejemplos de definiciones de API te recomendamos acudir a la documentación de OpenAPI. En concreto en esta página puedes encontrar ejemplos típicos y representativos del trabajo con OpenAPI.

Visualizar y probar tu API con Swagger UI

Una vez hayas desarrollado tu API, y tengas generada la documentación puedes utilizar Swagger UI para generar en instantes el sitio de la documentación interactivo.

Igualmente, puedes usar Docker para levantar un sitio web basado en Swagger UI, con estos comandos:

docker pull swaggerapi/swagger-ui

docker run -d -p 8080:8080 -e SWAGGER_JSON=/foo/swagger.yaml -v $(pwd)/swagger.yaml:/foo/swagger.yaml swaggerapi/swagger-ui

De todos modos, como hemos dicho antes, nuestra recomendación es que busques las integraciones que existan en tu framework de desarrollo con las herramientas de Swagger, ya que muchas veces no hace falta más que instalar un paquete específico que permite generar el sitio de Swagger UI a partir de la documentación escrita en las clases y métodos de tu propio proyecto.

Casos de uso comunes de Swagger en proyectos reales

Vamos a acabar mostrando algunos casos comunes donde podemos sacar partido a Swagger en proyectos reales.

Documentación de API públicas

Si tienes un API y quieres abrirla para que se pueda utilizar de manera pública deberías exponer un buen sitio de la documentación. Para eso utilizar Swagger es una de las principales opciones.

Integración de microservicios

Si tienes un sitio basado en microservicios tener una buena documentación de cada uno de esos servicios será esencial para conseguir integrarlos de una manera sencilla y correcta.

De este modo conseguirás mejorar la interoperabilidad entre los distintos servicios, comunicar mejor entre los equipos de desarrollo, aumentando su independencia y reduciendo los errores de integración.

Desarrollo colaborativo de API

Si varias personas trabajan en el desarrollo de un API, tener un único estándar para generar la documentación es básico, ya que todos tendrán que trabajar de una manera común.

Incluso puede ser muy útil comenzar por la especificación del servicio usando Swagger, que se comparte con todos los equipos, para que cualquiera de ellos sepa exactamente qué debe desarrollar y cómo debería hacerlo.

Paralelamente, el código YAML o JSON para definir el diseño del API se puede integrar en un repositorio Git, por lo que es fácilmente versionable y permite que se puedan hacer revisiones de los cambios a medida que sean propuestos, lo que mejora mucho la colaboración entre los equipos de desarrollo.