Swagger es un conjunto de herramientas de código abierto para escribir APIs basadas en REST. Simplifica el proceso de escribir APIs por muescas, especificando los estándares y proporcionando las herramientas necesarias para escribir APIs bonitas, seguras, con rendimiento y escalables.
¿Qué es Swagger?
Swagger te permite describir la estructura de tus APIS para que las máquinas puedan leerlas. La capacidad de las APIS para describir su propia estructura es la raíz de toda la maravilla de Swagger. ¿Por qué es tan genial? Bueno, al leer la estructura de tu API, puede construir automáticamente una hermosa e interactiva documentación de la API.
También puede generar automáticamente bibliotecas de clientes para tu API en muchos idiomas y explorar otras posibilidades como las pruebas automatizadas.
Swagger hace esto pidiendo a tu API que devuelva un YAML o JSON que contenga una descripción detallada de toda tu API. Este archivo es esencialmente un listado de recursos de tu API que se adhiere a la especificación OpenAPI.
La especificación te pide que incluya información como: ¿Cuáles son todas las operaciones que admite su API?, ¿Cuáles son los parámetros de su API y qué devuelve?, ¿Tu API necesita alguna autorización? E incluso cosas divertidas como las condiciones, la información de contacto y la licencia de uso de la API.
En el ámbito del software actual, no hay sistemas que funcionen en línea sin exponer una API. Hemos pasado de los sistemas monolíticos a los microservicios. Y todo el diseño de los microservicios se basa en las API de REST.
Las empresas no pueden permitirse ninguna laguna o fallo en la funcionalidad de las APIs, después de que todo el negocio se base en ellas.
¿Cómo ayuda Swagger a escribir APIs?
Cuando se escriben APIS desde cero, lo primero que nos viene a la cabeza como desarrolladores es:
¿Estoy haciendo las cosas bien? Me refiero a si he incluido el sistema de versiones en la API.
¿Están todos los controles de seguridad y cuarentena de datos en su lugar? ¿Y el diseño? A mí me parece que está bien. ¿Estoy manejando los errores correctamente o me falta algo?
Qué útil habría sido que hubiera habido una especificación global para escribir APIs.
Cuando tuve que escribir una API desde cero. Bueno, como había tantas cosas que aclarar, revisaba diferentes artículos en línea. Revisaba los documentos de las APIs expuestas por Twitter, Facebook y demás. Intentaba hacerme una idea de los estándares que cumplían. Era un proceso que consumía mucho tiempo.
Aquí es donde entra Swagger. Como he dicho antes, estandariza todo el proceso de escribir APIs. Nos ayuda a descubrir cosas que idealmente deberían ser detectadas en las fases iniciales de la escritura de software, nos ayuda a eliminarlas, ahorrando toneladas de tiempo de refactorización de código.
Veamos algunos de los superpoderes de Swagger.
Sea preciso con sus APIs a la primera
Ya lo sabemos, en la primera iteración del diseño del código, las cosas nunca son perfectas. Tenemos que seguir ajustando todo para que se ajuste a nuestras expectativas.
Es realmente largo correr iteraciones retocando las APIs una y otra vez.
Swagger ofrece una herramienta llamada Swagger Editor que nos ayuda a diseñar nuestras APIs basadas en la especificación OpenAPI.
OpenAPI ¡Woah! Parece que tenemos un estándar. ¡¡Hurra!!
¿Qué es el Editor Swagger?
Swagger Editor es una herramienta que nos ayuda a validar el diseño de nuestra API en tiempo real, comprueba el diseño con la Especificación de la API Abierta de la OEA y proporciona información visual sobre la marcha.
La herramienta del editor se puede ejecutar en cualquier lugar, ya sea localmente o en la web. Proporciona retroalimentación instantánea sobre el diseño de la API, señala si los errores no se manejan correctamente o si hay algún problema con la sintaxis.
También tiene funciones inteligentes de autocompletado, que nos permiten escribir el código más rápidamente. Es fácil de configurar y también permite a los desarrolladores crear stubs de servidor para la API para un desarrollo más rápido.
Con herramientas como Swagger Editor los desarrolladores tienen una visión en tiempo real de cómo se está desarrollando el diseño de la API. Obteniendo una respuesta instantánea de los stubs. También nos ayuda a analizar cómo un desarrollador de terceros interactuaría con la API.
Mi experiencia en el desarrollo de la industria con Swagger
En su día, cuando escribía una API de búsqueda para un proyecto de comercio electrónico desde cero. La tarea de la API era devolver resultados de búsqueda de productos contra las consultas alimentadas a ella.
Integramos Swagger es contar con ayuda para probar la API, para obtener resultados precisos y errores cuando se juega con varios parámetros locos diferentes.
Puntos a destacar:
Probar la API: Es realmente reconfortante para los devs ver su código, trabajar en la UI. Fue un poco fácil de comprender las cosas, especialmente cuando volví al proyecto después de un poco de descanso. Disparar comandos desde la UI de Swagger era siempre fácil o más comprensible.
Swagger UI ayuda al cliente, a tener una visión de la funcionalidad del sistema, ya que se desarrolla con el tiempo. Obviamente, no siempre se puede esperar que un cliente configure el código en su sistema o compruebe la respuesta de la API en el navegador ejecutando el código localmente.
¿Como es posible eso de que tu cliente en algún momento pueda ver el código? Sencillo se le puede enviar la url de la interfaz de usuario swagger y él puede fácilmente introducir los parámetros en la interfaz de usuario y echar un vistazo a la respuesta que el sistema devuelva. Mucho más fácil y simple diría yo.
Tener un diseño de API estándar en diferentes equipos
Swagger es para las API lo que un marco de trabajo es para escribir software.
Al igual que un marco ayuda a estandarizar el proceso de desarrollo de software. Swagger proporciona estándares globales a través de OpenAPI, permitiendo una cierta estructura universal a las APIs.
Sí deseas ampliar este conocimiento te dejo el enlace que lleva al video.
Diferentes personas tienen diferentes estilos al momento de codear, y si no fuera por los frameworks y estándares. Mantener el software escrito por cualquier otro desarrollador sería mucho más que una pesadilla.
Swagger especifica estándares de comportamiento común, patrones y una interfaz RESTful para las APIs. Los diferentes equipos de microservicios de una organización no tienen que romperse la cabeza comprendiendo, consumiendo y modificando APIs extranjeras.
Swagger ofrece una herramienta, Swagger Hub, que lleva incorporada una herramienta de estandarización de APIs que hace que el código se ajuste a las directrices de diseño de la organización.
Con esto, no importa si tienes un equipo de 3 o 300 personas. Las cosas siempre son sencillas.
¿Qué es SwaggerHub?
SwaggerHub es una plataforma de diseño y documentación para diseñar APIs con Open API.
Facilita la gestión dentro de diferentes equipos y proyectos mediante la creación de carpetas con diferentes APIs y niveles de permiso para una mejor organización.
Las cosas se pueden compartir con la gestión empresarial autorizada y las partes interesadas. Ayuda a los desarrolladores a trabajar junto con las partes interesadas, a incorporar nuevos cambios, a hacer que se revisen los cambios y a fusionar cosas. Estar en continua comunicación y hacer un seguimiento de los problemas.
SwaggerHub ofrece modelos de diseño comunes que pueden ser guardados en almacenes dedicados llamados dominios y pueden ser referenciados y reutilizados a través del código.
Al escribir el código del backend, nuestras APIs interactúan con otros servicios en el backend. En lugar de lanzar instancias de los mismos, SwaggerHub nos permite simular esas APIs facilitando un desarrollo más rápido.
Características que ayudan al desarrollo de APIs
Cuando se escriben APIs hay muchas cosas que hay que tener en cuenta, como el manejo de errores, la modularidad del código, el cumplimiento de protocolos y demás.
Swagger nos proporciona herramientas para codificar rápidamente nuestras APIs cuidando todas estas cosas. El uso de Swagger es el camino más rápido para crear un prototipo de API y luego un código desplegable en producción.
La herramienta de código abierto CodeGen de Swagger genera el código boilerplate al escribir la API. Esto te permite centrarte en la lógica de negocio en lugar de invertir tiempo en escribir la parte sintáctica.
Creación de la documentación de la API
Después de haber terminado de escribir el código. Otra tarea colosal y tediosa para los desarrolladores es escribir la documentación de su código. Me duele la cabeza cuando pienso en ello.
Swagger nos libra de esta tarea generando y manteniendo la documentación de la API por nosotros. ¡Ahorra un montón de tiempo! Además, no tenemos que volver y cambiar la documentación cada vez que el código cambia.
Toda la documentación es actualizada automáticamente por Swagger. También podemos generar diferentes versiones de la API según nuestras necesidades y caprichos.
También podemos configurar Swagger para que genere documentación para las APIs existentes.
Llegados a este punto y como complemento del video de ¿Como documentar tu código? Te dejo para que puedas checar la actualización del curso de NODE en el canal, chécalo porque de verdad está Chido.
Monitorización de la API en producción
Una vez que el código se despliega en la producción tiene que ser monitoreado para un comportamiento consistente. Con Swagger, podemos monitorizar nuestras APIs en producción para comprobar su disponibilidad, velocidad y funcionalidad.
Nos ayuda a seguir el comportamiento de la API asegurando una ejecución fluida y generando una alerta si detecta algún problema. Con la API Swagger, podemos gestionar mediante programación el proceso de monitorización de la API.
Quiero más
Por supuesto! gracias al apoyo que se ha conseguido por todos ustedes (comentando, suscribiéndote y compartiendo) se agregaron nuevos videos, en esta ocasión iniciamos el curso de testing en angular, curso de node, curso mongo y mucho más