OpenAPI and Swagger Ecosystem

Hola, soy Alex de DEV STORIES DOT EU. OpenAPI y el ecosistema Swagger, episodio 1 de 19. Las API impulsan la web moderna, pero ¿cómo se comunican realmente entre sí sin un ciclo interminable de ensayo y error? Necesitas una forma fiable de saber exactamente qué espera un servidor y qué te va a devolver, antes de escribir una sola línea de código. Ese mecanismo es el contrato de la API, regido por la Especificación OpenAPI. La Especificación OpenAPI es una interfaz estandarizada e independiente del lenguaje para las API REST. Imagínatelo como un plano arquitectónico. Cuando está bien definida, tanto una persona como una máquina pueden consultar este plano y comprender exactamente qué hace un servicio. No necesitan acceso al código fuente, no necesitan leer documentación en PDF aparte, y no necesitan inspeccionar el tráfico de red en tiempo real. La especificación describe claramente los endpoints disponibles, los inputs precisos que requieren y las estructuras exactas de los datos que devuelven. Está escrita en texto plano, usando YAML o JSON, lo que la hace universalmente legible tanto para herramientas automatizadas como para desarrolladores humanos. Si trabajas con API, probablemente hayas oído hablar del término Swagger. La gente suele usar Swagger y OpenAPI indistintamente, pero hoy en día representan conceptos totalmente distintos. Originalmente, la propia especificación se llamaba Swagger. En 2015, los creadores la donaron a la Linux Foundation, donde pasó a llamarse oficialmente Especificación OpenAPI. Hoy en día, OpenAPI se refiere estrictamente a las reglas y al estándar. Swagger se refiere al ecosistema de herramientas comerciales y open source creadas por SmartBear que implementan esas reglas. Por ejemplo, Swagger UI genera documentación interactiva, y Swagger Editor te ayuda a escribir los archivos. Escribes un documento OpenAPI, pero puede que utilices herramientas de Swagger para visualizarlo. Esto nos lleva al verdadero poder de la especificación, que es el desarrollo design-first. Sin un contrato claro, el desarrollo de la API suele ocurrir de forma lineal. El equipo de backend escribe el código, expone un nuevo endpoint, y luego entrega algo de documentación escrita. Mientras tanto, el equipo de frontend se queda de brazos cruzados, esperando a que el backend termine para poder empezar a montar la interfaz de usuario. Aquí está la clave. Cuando adoptas OpenAPI, inviertes ese proceso. Antes de que nadie escriba código de la aplicación, ambos equipos acuerdan el documento OpenAPI. Este archivo de texto se convierte en un contrato estricto que elimina todas las conjeturas. El equipo de backend lo usa para generar server stubs y validar que su implementación cumple con los requisitos acordados. Al mismo tiempo, el equipo de frontend usa exactamente el mismo documento para generar mock servers. Pueden empezar inmediatamente a construir la interfaz de usuario, haciendo peticiones de red a un backend simulado que se comporta exactamente igual que lo hará la API final. Ningún equipo bloquea al otro. Como este contrato es legible por máquinas, también resuelve de forma permanente el problema de la documentación obsoleta. Cuando un requisito de la API cambia, actualizas primero el archivo de especificación. Tus herramientas regeneran entonces automáticamente la documentación web, los mock servers y las librerías cliente. La documentación y el código se mantienen perfectamente sincronizados porque comparten una única fuente de la verdad. Una especificación de API no es solo un mecanismo para generar páginas web bonitas; es un protocolo de comunicación fundamental para tus equipos de ingeniería que transforma las suposiciones humanas en reglas ejecutables. Si te gusta el programa y quieres apoyarnos, busca DevStoriesEU en Patreon. Gracias por escucharnos. ¡Hasta la próxima!

Hola, soy Alex de DEV STORIES DOT EU. Ecosistema OpenAPI y Swagger, episodio 2 de 19. Escribir documentación es tedioso, pero ¿y si tu código escribiera la documentación y tu documentación escribiera el código? Este workflow bidireccional es la promesa principal del ecosistema open-source de Swagger. Un error común es pensar que hay que adoptar todo el ecosistema a la vez. No es necesario. El conjunto de herramientas es totalmente modular. Puedes elegir componentes individuales según las necesidades específicas de tu workflow, ya sea para simplemente renderizar documentación existente o para montar el scaffolding de un backend completamente nuevo. Las principales herramientas open-source funcionan como un pipeline. Diseñas la API en Swagger Editor, la visualizas en Swagger UI y automatizas las implementaciones con Swagger Codegen. Swagger Editor es donde comienza el diseño de la API. Es un entorno basado en navegador donde escribes tu especificación OpenAPI en YAML o JSON. A medida que escribes, el editor valida continuamente tu sintaxis según las reglas de la especificación OpenAPI. Si colocas un campo en el lugar equivocado o defines un tipo de dato no válido, el editor marca el error inmediatamente. Proporciona una vista de pantalla dividida en tiempo real, mostrando el texto en crudo a un lado y una vista previa visual al otro. Una vez que el contrato es válido, puedes pasar a la automatización con Swagger Codegen. Esta herramienta toma tu archivo de especificación OpenAPI y lo traduce a código fuente funcional. Es compatible con decenas de lenguajes y frameworks. Puedes generar server stubs, que proporcionan el routing y los controllers de boilerplate para tu backend. Alternativamente, puedes generar client SDKs, que las aplicaciones que la consumen utilizan para interactuar con tu API sin tener que escribir lógica de requests HTTP personalizada. Luego está Swagger UI. Esta herramienta parsea tu especificación y la renderiza como una página de documentación web interactiva. Va más allá del texto estático. Swagger UI genera inputs y botones de ejecución directamente a partir de las definiciones de tu API. Los usuarios pueden introducir parámetros, adjuntar tokens de autenticación, enviar requests HTTP reales a los endpoints de tu API e inspeccionar las respuestas directamente en el navegador. Imagina un workflow concreto que combine estas tres herramientas. Comienzas en Swagger Editor, redactando la especificación para una nueva API de gestión de usuarios. Defines los endpoints, los payloads de las requests y las respuestas esperadas. Una vez completado el contrato, introduces ese archivo en Swagger Codegen, configurándolo para que genere un server stub de Node.js. Codegen genera automáticamente la estructura de directorios, la configuración del package y los route handlers. Solo necesitas escribir la lógica de negocio específica y las consultas a la base de datos dentro de esos controllers preconfigurados. Mientras tanto, le pasas ese mismo archivo de especificación OpenAPI a tu equipo de QA, servido a través de Swagger UI. Los ingenieros de QA no necesitan leer tu archivo YAML ni mirar tu código Node.js. Abren la página web de Swagger UI, ven los inputs requeridos y empiezan a enviar payloads de prueba a tu nuevo servidor Node.js de inmediato. Aquí está la clave. El ecosistema open-source de Swagger transforma el desarrollo de APIs, pasando de escribir código backend y esperar que la documentación se mantenga precisa, a definir primero un contrato estricto, donde la documentación para el usuario y el boilerplate del servidor se generan a partir de la misma fuente de la verdad. Eso es todo por ahora. ¡Gracias por escuchar y sigue desarrollando!

Hola, soy Alex de DEV STORIES DOT EU. Ecosistema OpenAPI y Swagger, episodio 3 de 19. Antes de poder diseñar una API compleja, necesitas un lienzo en blanco, pero empezar con una estructura básica incorrecta romperá silenciosamente toda tu toolchain más adelante. Esto nos lleva a la Anatomía de un Documento OpenAPI. En esencia, un documento OpenAPI se define estrictamente como un objeto JSON. Puedes escribir tu archivo usando formato JSON o formato YAML. El tooling soporta ambos, y el modelo de datos subyacente sigue siendo exactamente el mismo. Como se mapea directamente a un objeto JSON estándar, las reglas de formato son rígidas. Cada nombre de campo es completamente case-sensitive. Si la especificación dicta que un nombre de campo va en minúsculas, escribirlo con la inicial en mayúscula hará que el parser lo ignore o lance un error. Al organizar tu proyecto, puedes elegir la estructura del documento. Puedes definir todo dentro de un único archivo monolítico. O bien, puedes dividir tus definiciones en una estructura multidocumento. En una configuración multidocumento, un archivo root actúa como punto de entrada y enlaza con archivos externos usando punteros de referencia. Tanto si usas un archivo como cincuenta, el parser los resuelve finalmente en un único objeto JSON lógico en memoria. Pongamos un escenario concreto. Estás empezando un proyecto nuevo. Creas un archivo de texto en blanco llamado openapi punto yaml. Antes de intentar diseñar ninguna lógica, quieres establecer una base validada. Para pasar un schema validator, tu lienzo vacío debe contener exactamente dos campos a nivel root. El primer campo obligatorio se llama openapi. Su valor es un string que especifica la versión exacta de la OpenAPI Specification que estás usando, como 3.1.0. Es súper común confundir este campo con la versión de tu propia API. Son cosas completamente independientes. El string de versión de openapi existe estrictamente para la compatibilidad del tooling. Cuando un generador de código o un visor de documentación abre tu archivo, lee primero este campo para determinar qué reglas de parsing aplicar. Si indicas 3.0.0 aquí, pero usas features de la 3.1.0, tus herramientas de validación fallarán porque están evaluando tu documento contra el conjunto de reglas equivocado. Aquí está la clave. El segundo campo root obligatorio es donde van los detalles reales de tu API. Este campo es el objeto info. El objeto info proporciona los metadatos de tu aplicación. No detallaremos su contenido interno aquí, aparte de decir que requiere un título y su propio string de versión. Ese string de versión interno dentro del objeto info es donde defines si tu aplicación está en la versión uno o en la versión dos. Una vez que tu archivo openapi punto yaml contiene solo estos dos campos root, openapi e info, tienes un documento OpenAPI estructuralmente completo. Puedes pasar este archivo por un validador ahora mismo y lo pasará sin problemas. Establecer esta estructura mínima válida asegura que tu parser y tu toolchain funcionan perfectamente antes de introducir la complejidad de la lógica de routing real. Gracias por escuchar, ¡happy coding a todos!

Hola, soy Alex de DEV STORIES DOT EU. Ecosistema OpenAPI y Swagger, episodio 4 de 19. Si tu API se cae, ¿cómo sabe un consumidor a quién contactar? La respuesta está justo al principio de tu spec. Hablamos de preparar el terreno: Info y Servers. Antes de que un desarrollador haga una request o inspeccione un data model, necesita contexto. Los objetos Info y Server proporcionan precisamente eso. Piensa en ellos como la portada y la agenda de contactos de tu API. El objeto Info es tu centro de metadatos. Aquí hay dos campos que son estrictamente obligatorios. El primero es el title, que es simplemente el nombre legible para humanos de tu aplicación. El segundo es la version. La gente suele confundir esto con la versión de la spec de OpenAPI. Son completamente diferentes. La versión de OpenAPI le dice al parser qué conjunto de reglas de sintaxis seguir. La version de Info es el número de release de tu propia API, algo como 1.0.5. Le indica al consumidor qué iteración del producto está viendo. Más allá de los campos obligatorios, el objeto Info te permite añadir contexto. Puedes incluir una description, que soporta formato CommonMark. Esto te permite escribir documentación detallada y legible con párrafos y enlaces directamente en la spec. También puedes definir un objeto contact que contenga un name, una URL y un email. Si algo se rompe o un desarrollador necesita acceso, esto le dice exactamente a dónde ir. Por último, el objeto license te permite especificar los términos legales bajo los cuales opera la API, requiriendo un name y, opcionalmente, una URL que apunte al texto de la licencia. Una vez que el objeto Info establece qué es la API, el array de Servers le dice al consumidor dónde vive. Sin esto, los consumidores saben qué hace tu API, pero no dónde encontrarla. Proporcionas un array de objetos Server que representan los diferentes entornos donde está hosteada tu API. Cada objeto Server requiere un único campo, que es la URL. Aquí está la clave. No estás limitado a una única base URL. Puedes definir múltiples entradas de servidor para reflejar tu infraestructura real. Por ejemplo, tu primer objeto Server podría contener tu URL de producción usando una dirección HTTPS segura, con una description que lo etiquete explícitamente como el entorno de producción. Tu segundo objeto Server podría apuntar a una URL de staging o sandbox, con una description indicando que es estrictamente para testing. Cuando estructuras tus servidores de esta manera, las herramientas de documentación interactiva y los generadores de clientes se vuelven mucho más potentes. En lugar de obligar a un desarrollador a configurar manualmente la base URL para cada request, simplemente pueden seleccionar staging o producción desde un menú desplegable en su interfaz. Las herramientas parsean tu array de Servers y enrutan automáticamente las requests al host correcto. También puedes usar URLs relativas si tu documento OpenAPI está hosteado directamente en el servidor que proporciona la API. Esto hace que sea más fácil hacer deploy del mismo archivo de spec en diferentes entornos sin actualizar constantemente la dirección del host. Definir objetos Info y Server precisos significa que tu API no es solo una colección suelta de operaciones, sino un servicio completamente identificado, legalmente claro y físicamente localizable. La calidad de cualquier integración automatizada dependerá por completo de la precisión de estas base URLs. Eso es todo por este episodio. ¡Gracias por escuchar, y sigue desarrollando!

Hola, soy Alex de DEV STORIES DOT EU. OpenAPI y el ecosistema Swagger, episodio 5 de 19. Toda API REST necesita endpoints, pero ¿cómo le demuestras matemáticamente a una máquina qué métodos HTTP están permitidos y dónde? Los mapeas lógicamente. Hoy veremos cómo mapear los paths y las operaciones de la API. Piensa en el Paths Object de OpenAPI como el router central de tu documentación. Actúa como un directorio que mapea URLs relativas a funcionalidades específicas. Antes de ver qué contiene, debemos aclarar un error común. Los paths siempre deben comenzar con una barra diagonal. Son estrictamente relativos a la URL de tu servidor, nunca absolutos. Si tu API está alojada en api punto example punto com, tu path es simplemente barra users, no el dominio completo. La especificación se basa en este formato exacto para añadir correctamente el path a la dirección base del servidor. Dentro del Paths Object, defines paths individuales usando keys de tipo string. El valor asignado a cada key de path se llama Path Item Object. Un Path Item Object es, fundamentalmente, solo un contenedor. Agrupa todos los métodos HTTP permitidos en esa URL específica. No dicta inputs ni outputs directamente. En su lugar, contiene keys que representan métodos HTTP estándar, como get, post, put o delete. Cuando mapeas uno de esos métodos HTTP dentro de un Path Item, el valor que le adjuntas es un Operation Object. El Operation Object es donde se define la acción real. Describe exactamente lo que un cliente puede hacer al enviar ese método específico a ese path exacto. Para visualizar la estructura, considera un endpoint estándar de gestión de usuarios. En tu Paths Object raíz, defines una key llamada barra users. El valor adjunto a ella es tu Path Item Object. Dentro de ese contenedor, defines una key get y una key post. La key get contiene un Operation Object que explica cómo la API devuelve una lista de usuarios. La key post contiene un Operation Object completamente independiente que describe cómo crear un nuevo usuario. Ambas operaciones comparten la idéntica URL barra users, pero la especificación las trata como acciones lógicas distintas anidadas bajo sus respectivas keys de método HTTP. Dentro de cada Operation Object, normalmente definirás dos campos para establecer su identidad: el summary y el operationId. El summary es un string corto destinado a lectores humanos. Para el método get en nuestro path barra users, el summary podría simplemente decir "Listar todos los usuarios registrados". Aparece en las interfaces de documentación generadas para que los desarrolladores puedan escanear rápidamente los endpoints disponibles. Aquí está la clave. El campo operationId está pensado para las máquinas. Es un string único que se utiliza para identificar la operación en todo el documento de tu API. Los generadores de código dependen en gran medida del operationId para nombrar las funciones y métodos dentro de los SDKs de cliente que construyen. Si le das a tu operación get un operationId de listUsers, el cliente Python o TypeScript generado incluirá una función llamada específicamente listUsers. Este string debe ser absolutamente único. Si dos operaciones comparten el mismo operationId, las herramientas de generación automatizada producirán código roto o crashearán por completo. La estructura se basa en un anidamiento estricto y predecible. Los paths se mapean a Path Items, los Path Items se mapean a métodos HTTP, y los métodos se mapean a Operation Objects definidos por identificadores únicos. Dominar esta jerarquía exacta garantiza que tanto los desarrolladores humanos como las herramientas de automatización posteriores puedan interactuar con la arquitectura de tu API sin tener que adivinar. Eso es todo por esta vez. ¡Nos vemos en la próxima!

Hola, soy Alex de DEV STORIES DOT EU. OpenAPI y el Swagger Ecosystem, episodio 6 de 19. Los endpoints estáticos tienen sus limitaciones. Para crear una API realmente útil, necesitas una forma de pasar argumentos dinámicos directamente a través de la request para cambiar cómo se ejecuta una operación o a qué datos apunta. Este episodio trata sobre los Dynamic Endpoints con parámetros. Empecemos con el path de la URL en sí. En OpenAPI, defines las secciones dinámicas de una URL usando path templating. Esto lo haces envolviendo el nombre de una variable entre llaves. Piensa en una API de e-commerce. Si quieres obtener un pedido específico, tu path se vería como barra orders barra abre llave orderId cierra llave. Dentro de tu documento OpenAPI, describes esta variable usando un Parameter Object. Especificas su ubicación estableciendo el campo in al valor path. A veces la gente intenta hacer que los path parameters sean opcionales. No puedes hacer esto. Un path parameter define estructuralmente la ruta. Si falta el parámetro, la ruta simplemente no existe. Debido a esta regla, cualquier parámetro donde la ubicación sea path debe establecer siempre el campo required a true. ¿Qué pasa si quieres modificadores opcionales? Eso nos lleva a la segunda ubicación, donde el campo in es igual a query. Los query parameters aparecen justo al final de la URL después de un signo de interrogación. Volviendo a nuestra API de e-commerce, puede que quieras una lista de pedidos, pero solo quieres ver los que ya están en tránsito. Añades signo de interrogación status igual a shipped a la URL. A diferencia de los path parameters, los query parameters no definen la ubicación del recurso. Filtran o modifican el resultado, lo que significa que su campo required puede establecerse en true o false. La URL no es el único lugar para pasar parámetros. El Parameter Object soporta dos ubicaciones más. Establecer el campo in a header te permite definir headers HTTP personalizados que espera tu operación. Por ejemplo, podrías requerir un header personalizado que indique un tipo de dispositivo cliente específico. Ten en cuenta que los headers estándar como Accept o Authorization están estrictamente excluidos del Parameter Object porque se gestionan en otra parte de OpenAPI. Finalmente, establecer la ubicación a cookie te permite documentar parámetros pasados a través de cookies del navegador, como un token de sesión temporal. Declarar dónde vive un parámetro es solo el primer paso. También necesitas definir su forma. Dentro del Parameter Object, usas el campo schema para definir el tipo de datos subyacente. Esto le dice al consumidor de la API exactamente si ese orderId es un integer, un string, o un formato específico como un UUID. Luego tienes el campo style. Esto dicta cómo se serializa el parámetro en la request HTTP. La serialización importa muchísimo cuando estás pasando datos complejos como arrays u objects. Si pasas una lista de estados en un query string, el campo style determina el formato. Un valor de style de form podría separar múltiples valores con un ampersand, mientras que un valor de style de simple genera una lista separada por comas. Al combinar los campos location, schema y style, le das al cliente instrucciones exactas sobre cómo formatear la request de red. Aquí está la clave. El Parameter Object no solo describe los inputs como cortesía. Dicta estrictamente la huella exacta de lo que acepta una operación, imponiendo tipos de datos y formatos antes de que se ejecute una sola línea de la lógica de tu backend. Si estos episodios te resultan útiles, puedes apoyar el programa buscando DevStoriesEU en Patreon. Eso es todo por este episodio. Gracias por escuchar, y ¡sigue programando!

Hola, soy Alex de DEV STORIES DOT EU. OpenAPI y el Ecosistema Swagger, episodio 7 de 19. Cuando envías cientos de campos a una API, los query parameters se quedan cortos. Necesitas un paquete estructurado. Ese paquete se define estructurando los Request Bodies de entrada. Mientras que las requests GET dependen del URL path y la query string, las requests POST, PUT y PATCH hacen el trabajo pesado llevando un payload. Este payload contiene datos complejos y anidados. En las especificaciones más antiguas de Swagger 2.0, quizá recuerdes que definías body parameters o form parameters directamente junto a los inputs de header y path. La versión 3 de OpenAPI cambió esto radicalmente. Eliminó por completo los body parameters e introdujo un único Request Body Object dedicado. El Request Body Object se sitúa a nivel de operación en el diseño de tu API. Su característica principal es que depende muchísimo del content negotiation. No solo describes los datos; los mapeas a media types específicos. Este mapeo ocurre dentro del content map. El content map es un diccionario donde las keys son tipos MIME estándar, como application barra json, y los values son Media Type Objects que detallan cómo es ese payload específico. Imagina un cliente subiendo un nuevo perfil de usuario. El perfil contiene un nombre, un email, preferencias de usuario y un objeto address anidado. En lugar de meter todo esto a la fuerza en variables de la URL, el cliente envía un payload en JSON. En tu documento OpenAPI, bajo el request body, creas un content map con la key exacta application barra json. Esto declara explícitamente que la API solo acepta JSON para esta operación. Si un cliente intenta enviar XML o texto plano, el servidor sabe inmediatamente que debe rechazar la request con un error de unsupported media type. Esta estructura es súper flexible. Si la subida de tu perfil de usuario requiere una foto de perfil junto a los datos de texto, lo gestionas exactamente en el mismo sitio. Añades una segunda key al content map para multipart barra form-data. Este Media Type Object especifica entonces las reglas para el payload mixto. Cada media type tiene su propia definición independiente. Esto permite que exactamente el mismo endpoint de la API procese formatos de datos fundamentalmente distintos, basándose únicamente en el header Content-Type que el cliente envía en la request HTTP. Dentro del propio Request Body Object, junto al content map, encontrarás un flag required. Esta es una simple propiedad booleana. Ponerla a true significa que la request fallará inmediatamente si el cliente envía un body vacío. Fuerza la presencia del payload antes incluso de que el servidor intente validar los datos de su interior. Las reglas estructurales reales del propio payload se gestionan mediante un schema adjunto al Media Type Object, aunque la mecánica profunda del diseño de JSON Schema la cubriremos en el episodio diez. Aquí está la clave del asunto. El Request Body Object desacopla el payload de datos en crudo de los parámetros de transporte HTTP, permitiendo que un único endpoint aplique reglas de validación completamente diferentes basadas únicamente en el media type declarado en el content map. Eso es todo por este episodio. ¡Gracias por escuchar, y sigue creando!

Hola, soy Alex de DEV STORIES DOT EU. OpenAPI y el ecosistema Swagger, episodio 8 de 19. La mayoría de los developers documentan el happy path, pero la verdadera resiliencia de una API viene de definir estrictamente y con exactitud cómo van a fallar las cosas. Si solo le dices a los clientes qué pasa cuando todo va perfecto, tu API solo está documentada a medias. Hoy vamos a ver las Expectations y las Error Responses. En OpenAPI, las responses sirven como la garantía definitiva del contrato. Formalizan la promesa de que, si el cliente envía una request específica, la API devolverá un payload conocido o un error estructurado. Esta promesa la gestiona el Responses Object. Piénsalo como una tabla de enrutamiento para los resultados. Las keys en este mapa son códigos de estado HTTP escritos como strings, como el texto 200 o 404. Los valores asociados a esas keys son Response Objects individuales, que detallan exactamente qué se le devuelve al cliente por la red. Aquí está la clave sobre cómo formatear estos objetos. En gran parte de OpenAPI, los campos description son completamente opcionales. Los usas cuando quieres añadir contexto útil para otros developers. En un Response Object, el campo description es estrictamente obligatorio. Si lo omites, toda la definición de tu API se vuelve inválida. No hace falta que sea un párrafo largo. Una frase corta y precisa que explique el resultado es suficiente, pero el parser exigirá su presencia. Imagina un escenario práctico donde un cliente hace una request de un perfil de usuario específico. Para el resultado exitoso, defines una key para el string 200. Dentro de ese Response Object, proporcionas tu description obligatoria, quizás indicando Recuperación de usuario exitosa. A continuación, defines el campo content. Este campo mapea un media type, casi siempre application/json, directamente al schema que define la estructura de tu objeto de usuario. El código del cliente ahora sabe exactamente qué propiedades esperar cuando la llamada tiene éxito. Eso cubre el resultado esperado. Ahora tienes que documentar el fallo. Bajo el mismo Responses Object, defines otra key para 404. El campo description requerido podría decir simplemente Usuario no encontrado. Igual que en el caso de éxito, el campo content aquí mapea application/json a un schema, pero esta vez apunta a tu estructura de error estandarizada. Gracias a este contrato explícito, la aplicación cliente puede parsear de forma segura la error response y mostrar un prompt útil al usuario final en lugar de crashear ante datos inesperados. Siempre habrá casos en los que no puedas predecir cada código de error que tu arquitectura pueda producir. Un reverse proxy podría lanzar un 502 Bad Gateway, o un web application firewall podría inyectar un 403 Forbidden. Aquí es donde entra en juego el wildcard default. En lugar de un código de estado HTTP numérico, usas la palabra exacta default como key. Esto actúa como una definición catch-all. Si el servidor devuelve cualquier código de estado que no hayas listado explícitamente en el Responses Object, el cliente hace un fallback a la estructura definida bajo default. Actúa como una red de seguridad para el error handling genérico, asegurando que el cliente siga sabiendo cómo leer el payload del error. Una definición de API verdaderamente robusta no solo explica el escenario perfecto; proporciona un mapa preciso y predecible de todas las posibles formas en las que el sistema puede fallar. Gracias por pasar unos minutos conmigo. Hasta la próxima, cuídate.

Hola, soy Alex de DEV STORIES DOT EU. Ecosistema OpenAPI y Swagger, episodio 9 de 19. Si tu API tiene 100 endpoints y todos devuelven la misma estructura de paginación, copiar y pegar es una receta para el desastre. Un pequeño cambio en el nombre de un campo implica buscar manualmente 100 definiciones dispersas por todo el documento. El mecanismo estructural que resuelve esta tensión es la reutilización con Components. La especificación OpenAPI aborda el exceso de código en la especificación mediante una sección dedicada en el nivel raíz llamada Components Object. Imagínalo como un diccionario centralizado o una biblioteca interna para la definición de tu API. En lugar de definir estructuras de datos complejas, query parameters estándar o respuestas repetitivas del servidor inline debajo de cada path individual, las declaras exactamente una vez dentro del Components Object. Esto establece una única fuente de la verdad estricta. Antes de explicar la mecánica, necesito aclarar una idea errónea común sobre cómo se comporta esta sección. Definir un schema, un header o un parameter dentro del Components Object no lo expone automáticamente en la documentación de tu API ni en tu lógica de routing. La sección de components es completamente pasiva. No tiene ningún efecto directo en tus endpoints. Un component solo importa si un path o una operation real apunta explícitamente a él. Para poner un component en servicio activo, utilizas el Reference Object. En la sintaxis de OpenAPI, esto se representa con la keyword dólar ref. El Reference Object utiliza un JSON Pointer para decirle al tooling exactamente dónde localizar la definición compartida. Un string de pointer interno estándar empieza con un símbolo de almohadilla, seguido de una barra, la palabra components, otra barra, el nombre de la categoría específica y, finalmente, el nombre personalizado que le diste a tu objeto. Aterricemos esto en un escenario concreto. Casi todas las API requieren una forma consistente de devolver errores del cliente y del servidor. Quieres que tus respuestas 400 Bad Request y 500 Internal Server Error compartan exactamente la misma estructura en todos los endpoints, conteniendo quizás un código de error integer y un string de mensaje descriptivo. Primero, bajas hasta tu Components Object raíz. Dentro de él, abres una categoría llamada schemas. Debajo de schemas, defines un nuevo objeto genérico llamado ErrorModel y especificas tus properties code y message. Tu estructura de error genérica ahora está guardada de forma segura. A continuación, subes a los paths de tu API. Cuando defines la respuesta de nivel 400 para un endpoint de creación de usuarios, omites por completo escribir las properties del schema inline. En su lugar, proporcionas una key dólar ref. Su valor es el path exacto a tu schema almacenado: almohadilla barra components barra schemas barra ErrorModel. Insertas exactamente ese mismo string de referencia en la respuesta de nivel 500. Repites esta referencia en tus endpoints de facturación, tus endpoints de autenticación y tus endpoints de búsqueda. Docenas de operations ahora apuntan a una única definición. Esta estrategia organizativa va mucho más allá de los schemas. El Components Object proporciona categorías específicas para varios elementos de la API. Puedes almacenar argumentos de paginación estándar dentro de la categoría parameters. Puedes definir estructuras de payload completas en requestBodies, o requisitos de autorización estándar en securitySchemes. La lógica operativa permanece idéntica en todos ellos. Define el objeto una sola vez en su contenedor correspondiente y luego conéctalo a tus paths operativos usando una referencia. Aquí está la idea clave. Construir una especificación de API mantenible trata fundamentalmente sobre controlar la duplicación. Cuando surge un nuevo requisito que te obliga a añadir un campo timestamp a cada respuesta de error, utilizar components significa que editas el ErrorModel en exactamente un lugar, y cada operation en toda tu API hereda automáticamente la actualización. Eso es todo por hoy. ¡Hasta la próxima!

Hola, soy Alex de DEV STORIES DOT EU. OpenAPI y el ecosistema Swagger, episodio 10 de 19. Sabes lo que es un integer, pero tu base de datos necesita saber si es un valor de 32 o 64 bits. Los schemas solucionan este problema. Este episodio trata exclusivamente sobre Data Types y Schemas. El Schema Object actúa como el motor de validación riguroso de tu API. Se sitúa justo debajo de tus parámetros, request bodies y responses. En lugar de simplemente decirle a un cliente que envíe un payload JSON genérico, un schema dicta la forma, el tipo y los límites exactos de esos datos. Actúa como un filtro estricto en el límite de tu sistema. Si una request entrante no coincide con las reglas definidas en el schema, falla la validación incluso antes de que la lógica de tu aplicación la vea. Históricamente, los desarrolladores se topaban con un importante obstáculo al definir estas reglas. La versión 3.0 de OpenAPI utilizaba su propio dialecto personalizado de JSON Schema. Aunque se acercaba al estándar, era fundamentalmente incompatible en algunos aspectos frustrantes, lo que generaba innumerables dolores de cabeza con el tooling. La versión 3.1 de OpenAPI resuelve esto por completo. Ya no es un dialecto personalizado. OpenAPI 3.1 está totalmente alineado con el JSON Schema moderno. Específicamente, actúa como un superset de JSON Schema Draft 2020-12. Esto significa que cualquier documento JSON Schema estándar que ya tengas es automáticamente un schema OpenAPI 3.1 válido. Ser un superset simplemente significa que OpenAPI añade algunas keywords específicas de la API por encima, como identificadores de configuración XML, sin romper el estándar subyacente. En el núcleo de estas reglas de schema se encuentra la keyword type. OpenAPI se basa en los tipos de datos primitivos definidos por JSON Schema. Tienes strings, integers, numbers y booleans. La distinción entre number e integer se aplica estrictamente. El tipo number maneja valores de coma flotante y doubles, mientras que el tipo integer rechaza específicamente cualquier valor con fracción decimal. Aquí está la clave. Saber que algo es simplemente un string o un integer rara vez proporciona suficiente contexto para un sistema backend. Aquí es donde el modificador format se vuelve esencial. La keyword format reduce un tipo primitivo amplio a algo específico para lo que tu código puede asignar memoria o contra lo que puede validar. El tipo primitivo le indica al parser JSON cómo leer los datos en crudo, y el format le indica a tu aplicación exactamente cómo interpretar el valor. Por ejemplo, si defines una propiedad como un integer, puedes añadir un format de int32 o int64 para especificar su tamaño exacto en bytes. Si tu tipo es un string, puedes aplicar un format como date-time, password o email. La especificación OpenAPI define un registro estándar de estos formats, pero el campo es, en última instancia, un string abierto, lo que significa que el tooling puede soportar formats personalizados si tu aplicación los requiere. Veamos un escenario concreto. Necesitas definir un objeto User para un endpoint de registro. Empiezas creando un schema de tipo object. Dentro de este objeto, defines dos propiedades, un ID y una dirección de email. Para la propiedad ID, configuras el type como integer y el format como int64. Para la propiedad de dirección de email, configuras el type como string y el format como email. Finalmente, especificas un array de propiedades requeridas que contiene los nombres de los campos ID y email. Ahora tienes un contrato estricto y ejecutable. Si un cliente envía una propiedad email que no se parece a una dirección de email válida, o un ID que excede el límite numérico de 64 bits, el API gateway o framework rechaza el payload inmediatamente. La precisión en el límite de la API te evita tener que escribir una lógica de verificación de datos interminable dentro de tus controllers. Eso es todo por este episodio. Gracias por escuchar, ¡y sigue desarrollando!

Hola, soy Alex de DEV STORIES DOT EU. Ecosistema OpenAPI y Swagger, episodio 11 de 19. Antes de que puedas proteger un endpoint sensible, tienes que declarar formalmente qué aspecto tiene exactamente una tarjeta de identificación válida. No puedes simplemente exigirle autenticación a un cliente. Tienes que especificar el mecanismo exacto que tienen que usar, las URLs a las que tienen que llamar y los parámetros que tienen que enviar. Definir los security schemes es como solucionas esto. Piensa en este paso como hacer un inventario de las cerraduras que existen en tu sistema. Estás describiendo los tipos de cerraduras disponibles, pero en realidad aún no las estás instalando en ninguna puerta específica. En OpenAPI, defines estas cerraduras dentro del objeto components, específicamente bajo una sección llamada security schemes. Cada cerradura recibe un nombre de referencia personalizado que tú eliges. Dentro de ese nombre personalizado, declaras su type y sus properties requeridas. Hay cinco tipos principales de security schemes en la especificación OpenAPI tres punto uno. El primero es el type http. Esto cubre los mecanismos de autenticación HTTP estándar definidos por el RFC 7235, como la autenticación Basic o Bearer. Para definir un scheme de token HTTP Bearer estándar, creas una entrada bajo security schemes. Pones la property type con el string http, y pones la property scheme con el string bearer. También puedes añadir opcionalmente una property bearer format para dar una pista sobre el tipo de token, como por ejemplo pasando el string JWT. Aquí está la clave. Cuando usas el scheme http bearer, la especificación asume implícitamente que el token se enviará en la header Authorization estándar de HTTP. No le dices a OpenAPI dónde mirar. Pero el segundo tipo, el scheme api key, es completamente diferente. Para una API key, tienes que especificar explícitamente tanto la property name, que es el nombre exacto del campo, como la property in, que dicta dónde va la key. La property in solo acepta tres valores: query, header o cookie. Si esperas una header personalizada como X API Key, usa el type api key. Si usas headers Authorization estándar, usa el type http. El tercer tipo es oauth2. Este requiere más configuración estructural porque OAuth2 tiene múltiples flows distintos. Para definir un flow complejo de authorization code de OAuth2, empiezas poniendo el type a oauth2. Luego proporcionas un objeto flows. Dentro de flows, añades un objeto authorization code. Este objeto anidado requiere dos URLs específicas. Proporcionas la authorization url donde el usuario inicia sesión, y la token url donde la aplicación intercambia un código por un token. También tienes que proporcionar un objeto scopes, que mapea nombres de scope específicos a descripciones cortas de texto sobre lo que permiten esos scopes. El cuarto tipo es open id connect. Este es mucho más sencillo de declarar que OAuth2. Pones el type a open id connect y proporcionas una única property open id connect url. Esta apunta directamente al conocido discovery document que los clientes usan para configurarse automáticamente. Finalmente, el quinto tipo es mutual t l s, que significa mutual Transport Layer Security. Simplemente pones el type a mutual t l s. Esto señala que el cliente tiene que proporcionar un certificado X 509 durante el handshake inicial de TLS para autenticarse, totalmente fuera de la capa de aplicación HTTP. La conclusión más útil aquí es que definir los security schemes separa el mecanismo de autenticación de los endpoints que lo requieren. Construyes tus cerraduras una vez en un catálogo centralizado, asegurando que los clientes sepan exactamente cómo formatear sus credenciales antes de que intenten siquiera llamar a la puerta. Por cierto, si quieres apoyar el programa, puedes buscar DevStoriesEU en Patreon. Eso es todo por este episodio. Gracias por escuchar, ¡y a seguir programando!

Hola, soy Alex de DEV STORIES DOT EU. Ecosistema OpenAPI y Swagger, episodio 12 de 19. Aplicar la seguridad es un ejercicio de equilibrio: quieres cerrar toda la caja fuerte a nivel global, pero dejar el vestíbulo abierto para los visitantes. Para hacer eso sin quedarte fuera, tienes que entender cómo OpenAPI aplica los Security Requirements. Una vez que has definido tus security schemes en la sección components de tu documento OpenAPI, tienes que vincularlos a tus endpoints. Esto lo haces usando el array security. Este array contiene Security Requirement Objects, que hacen referencia a los nombres de los esquemas que creaste antes. Puedes declarar este array security en dos sitios: a nivel global en la raíz de tu documento OpenAPI, o a nivel local dentro de un Operation Object específico. Si lo defines en la raíz, absolutamente todos los endpoints de tu API heredan ese requisito. Si lo defines dentro de una operación, sobrescribe la configuración global por completo. No se fusiona con los ajustes globales, los reemplaza totalmente. Imagina un escenario donde estableces un requisito global que exige que cada ruta de la API necesite un Bearer token. Eso protege la caja fuerte. Pero también tienes una ruta de login. Si la ruta de login hereda ese requisito global del token, los nuevos usuarios nunca podrán autenticarse porque todavía no tienen un token. Tienes que anular el bloqueo global. Un error muy común es simplemente omitir el campo security en la operación de login, asumiendo que eso implica que no hay seguridad. Si omites el campo, la operación simplemente asume el requisito global por defecto, y tus usuarios se quedan fuera. Para permitir explícitamente el acceso anónimo, tienes que definir el array security en la operación de login y meter un objeto vacío dentro. Ese objeto vacío le dice a OpenAPI que el requisito para acceder a este endpoint específico es absolutamente nada. El bloqueo global se ignora, y los visitantes pueden llegar al vestíbulo. Aquí es donde la cosa se pone interesante. La forma en que estructuras los elementos en el array security dicta la lógica de tu autenticación. Maneja escenarios de OR lógico y AND lógico basándose puramente en los límites de los objetos. Si tu array contiene dos Security Requirement Objects separados, por ejemplo, un objeto que pide una API key y un segundo objeto separado que pide OAuth2, eso crea un OR lógico. La API aceptará una petición si el cliente satisface el primer objeto o el segundo. Si necesitas un AND lógico, cambias los límites. Digamos que una petición debe tener tanto un token OAuth2 como una firma de header personalizado. Pones ambos nombres de esquema dentro de un único Security Requirement Object. Como comparten el mismo objeto, la API requiere que todos sean válidos antes de dejar pasar la petición. Cuando escribes estos objetos, mapeas el nombre de tu esquema a un array. Si estás usando OAuth2 u OpenID Connect, ese array lista los scopes específicos requeridos para la operación, como leer o escribir datos. Si estás usando una API key o un esquema HTTP básico, los scopes no se aplican, así que debes mapear el nombre del esquema a un array vacío para cumplir con la especificación. La estructura física de tu array security es tu herramienta principal para definir la lógica de acceso. Domina la diferencia de límites entre listar elementos en el array frente a listar elementos dentro de un único objeto, y podrás construir cualquier flujo de autenticación que tu sistema necesite. Eso es todo por este episodio. ¡Gracias por escuchar, y sigue programando!

Hola, soy Alex de DEV STORIES DOT EU. OpenAPI y el ecosistema Swagger, episodio 13 de 19. REST es ideal para hacer preguntas, pero ¿qué sucede cuando tu API necesita ser la que inicie la conversación? Las APIs asíncronas con webhooks lo solucionan enviando datos en el momento en que ocurre un evento, eliminando por completo la necesidad de hacer polling constante. Históricamente, los consumidores tenían que escribir scripts que comprobaban repetidamente tus endpoints para ver si un estado había cambiado. Esto era ineficiente tanto para sus servidores como para el tuyo. OpenAPI 3.1 resolvió esta limitación al introducir el campo webhooks directamente en la raíz del documento OpenAPI. Esta incorporación trajo soporte de primer nivel para la comunicación asíncrona y event-driven a las especificaciones estándar de APIs. En lugar de documentar únicamente lo que un cliente envía a tu servidor, el campo webhooks te permite documentar exactamente lo contrario. Defines las peticiones HTTP que tu plataforma iniciará y enviará al servidor del consumidor. Es necesario establecer una línea clara entre webhooks y callbacks, ya que la especificación OpenAPI los gestiona de forma muy diferente. La diferencia radica en cómo se registra la URL de destino. Los callbacks se activan mediante una petición a la API específica y activa. Un cliente hace una petición a un endpoint de suscripción en tu API y proporciona una URL de destino directamente ahí, en el payload de la petición. Dado que están vinculados a una operación, los callbacks se definen dentro de ese Operation Object específico. Los webhooks se registran out-of-band. Un desarrollador inicia sesión en un dashboard de administración, navega a una página de configuración y pega su URL de destino en un formulario. A la especificación de la API no le importa cómo se obtuvo la URL. Dado que los webhooks existen independientemente de cualquier llamada a la API específica en runtime, se ubican en el nivel más alto de tu documento OpenAPI, justo al lado de tus paths y components estándar. Para documentar un webhook, abres el mapa webhooks de nivel raíz. Cada key dentro de este mapa es un simple string que da nombre al evento. Por ejemplo, podrías usar el string payment dot successful. El valor asociado a esa key es un Path Item Object estándar. Esta es exactamente la misma estructura que usas para definir tus endpoints REST normales. Dentro de ese Path Item Object, declaras el método HTTP que tu plataforma utilizará para entregar el evento, que casi siempre es una petición POST. Aquí está la clave. La perspectiva se invierte por completo, pero las herramientas siguen siendo idénticas. Usas Schema Objects estándar para definir el request body que enviará tu plataforma. En el escenario de payment dot successful, especificas que el payload será un objeto JSON que contiene un ID de pago único, el importe exacto cobrado y un timestamp. También puedes definir headers, lo cual es crítico para los webhooks porque normalmente necesitas documentar un header de firma criptográfica para que el consumidor pueda verificar que el payload realmente viene de ti. Finalmente, documentas las respuestas que esperas recibir del consumidor. Podrías indicar que tu sistema espera un status code 200 OK en un plazo de tres segundos; de lo contrario, tu sistema reintentará la entrega más tarde. Al estandarizar esta documentación de API inversa, das a los consumidores todo lo que necesitan para generar su propio código de servidor. Saben exactamente qué payload parsear, qué headers validar y qué status codes devolver. El campo webhooks de nivel raíz cambia el diseño de APIs de simples interacciones request-response a una arquitectura event-driven totalmente documentada. Eso es todo por este episodio. Gracias por escuchar, ¡y sigue programando!

Hola, soy Alex de DEV STORIES DOT EU. Ecosistema OpenAPI y Swagger, episodio 14 de 19. Crear un usuario es el primer paso, pero ¿cómo sabe un cliente automatizado de forma intuitiva a dónde ir para obtener el perfil de ese usuario a continuación? Podrías hardcodear el workflow en el código de tu cliente, pero eso se rompe en el momento en que cambia la estructura de tu API. La solución a esto son las transiciones de estado con Links. En OpenAPI, el objeto Link se encuentra dentro de una respuesta y mapea datos de esa respuesta a los parámetros de otra operación. Para que quede perfectamente claro, los links no ejecutan requests automáticamente. No convierten OpenAPI en un motor de orquestación activo. Simplemente proporcionan instrucciones estáticas a tu tooling, SDKs o documentación sobre cómo construir la siguiente request lógica en un workflow. Si has construido APIs antes, puede que pienses que esto suena exactamente igual que HATEOAS estricto, donde el servidor envía links hipermedia dinámicos dentro del payload de la respuesta. Los links de OpenAPI ofrecen una alternativa developer-friendly a ese enfoque. En lugar de obligar al backend a inyectar URIs dinámicas en cada respuesta en runtime, los links de OpenAPI describen las transiciones de estado del workflow de forma estática dentro de la propia definición de la API. Las herramientas del cliente pueden entender el workflow sin necesidad de parsear payloads en vivo para descubrir qué acciones son posibles. La lógica fluye conectando una respuesta de origen con una operación de destino. Imagina una request POST estándar que se usa para crear un nuevo usuario. La respuesta devuelve un body JSON que contiene un ID de usuario recién generado. Dentro de la definición de esa respuesta específica, añades un mapa de links. Cada entrada en este mapa define una relación con otra operación, como la request GET que recupera el perfil del usuario. Identificas la operación de destino usando uno de dos campos mutuamente excluyentes. El primero es operation ID, que es un simple string que coincide con el identificador único de la operación de destino. El segundo es operation reference, que usa un JSON Pointer estándar para navegar por el documento OpenAPI y localizar el path de destino y el método HTTP. Operation ID suele ser más limpio si tu API los define de forma consistente, mientras que operation reference es útil para apuntar a operaciones en documentos OpenAPI externos. Una vez que apuntas a la operación de destino, debes pasarle los datos correctos. Esto lo haces usando un mapa de parameters. Las keys en este mapa representan los nombres de los parámetros que espera la operación de destino, como el path parameter del ID de usuario. Los valores son runtime expressions que le dicen al tooling de dónde extraer esos datos del contexto actual. Una runtime expression es una sintaxis específica que evalúa datos durante la llamada a la API. Puedes escribir una expresión que le indique al cliente que mire el body de la respuesta, localice el campo ID y extraiga su valor. No estás limitado al body de la respuesta. Las runtime expressions pueden extraer valores de los headers de la respuesta, el path de la request original o los query parameters de la request original. Si la operación de destino requiere un request body en lugar de solo parámetros, el objeto Link proporciona un campo request body. Esto te permite mapear una runtime expression directamente en el payload de la request posterior. Cuando un generador de SDKs procesa estos links, puede crear automáticamente llamadas a métodos encadenadas, permitiendo a un desarrollador crear un usuario y llamar inmediatamente a un método generado para obtener el perfil en el objeto devuelto. Aquí está la clave. El verdadero poder del objeto Link es que cierra la brecha entre endpoints aislados, convirtiendo un diccionario plano de paths de API en un mapa navegable de acciones que tus clientes pueden seguir con confianza sin depender de URLs hardcodeadas. Gracias por escuchar. ¡Nos vemos en la próxima!

Hola, soy Alex de DEV STORIES DOT EU. Ecosistema OpenAPI y Swagger, episodio 15 de 19. Una especificación JSON perfectamente elaborada es inútil si los desarrolladores que consumen tu API se niegan a leerla. Necesitas hacerla visual. Ahí es precisamente donde entran en juego los Interactive Docs con Swagger UI. Hasta ahora, hemos tratado un documento OpenAPI como un archivo de texto plano que contiene endpoints y schemas. Swagger UI toma ese archivo JSON o YAML y lo convierte en una página web interactiva. Esto cambia por completo el enfoque, pasando de escribir la especificación a consumirla activamente. Los desarrolladores pueden explorar los endpoints, inspeccionar los query parameters y ejecutar peticiones HTTP en vivo directamente desde su navegador. Actúa como un puente entre un contrato estático y una herramienta de testing en vivo. Si quieres alojar esta interfaz tú mismo, probablemente empezarás con Node Package Manager. Al instalarlo, te encontrarás inmediatamente con una trampa de nombres muy común. Hay dos paquetes principales. El primero se llama simplemente swagger guion ui. No uses este paquete a menos que estés usando una build tool como Webpack o Rollup para compilar una aplicación front-end personalizada. Si tu objetivo es simplemente alojar la documentación directamente, necesitas el paquete llamado swagger guion ui guion dist. El sufijo dist significa distribución. Contiene los static assets pre-built y listos para servir, como los bundles principales de JavaScript, las hojas de estilo CSS y un archivo index HTML. Sueltas estos archivos en cualquier servidor web básico y funcionan de inmediato. Si no quieres gestionar node packages ni archivos locales para nada, puedes embeber esos mismos static assets en una página web vacía usando una content delivery network como unpkg. Añades una etiqueta style de HTML estándar que apunte al archivo CSS de Swagger UI en unpkg, y una etiqueta script para el bundle de JavaScript. Luego, escribes un breve bloque de inicialización en JavaScript que apunte a la dirección web donde se encuentra tu archivo OpenAPI. El navegador carga la página vacía, obtiene los assets de la red, recupera tu especificación y renderiza la interfaz completa automáticamente. Aquí está la clave. Ni siquiera necesitas escribir HTML para hacer deploy de esta interfaz. El método más limpio y escalable es usar la imagen oficial de Docker. Simplemente haces pull de la imagen llamada swaggerapi barra swagger guion ui. Al ejecutarla out of the box, se cargará un ejemplo predeterminado de Petstore. Para servir tu propio archivo local en su lugar, montas tu especificación en el contenedor como un volumen. Luego, pasas una variable de entorno llamada SWAGGER guion bajo JSON, apuntando a la ruta exacta donde montaste ese archivo dentro del contenedor. Primero, ejecutas el comando Docker run y mapeas un puerto expuesto como el ochenta a tu máquina local. A continuación, mapeas tu directorio local que contiene tu archivo swagger punto json a un directorio dentro del contenedor. Finalmente, configuras la variable de entorno SWAGGER guion bajo JSON para que apunte a esa ruta de archivo interna específica. Cuando el contenedor se inicia, levanta un servidor web ligero, lee tu variable de entorno para localizar la especificación y sirve la UI. Obtienes un portal de documentación completamente funcional en segundos sin instalar ninguna dependencia local. Al desacoplar el renderizado de la documentación del propio código fuente de la API, Swagger UI convierte un contrato de texto estático en un entorno de testing ejecutable que viaja sin problemas por cualquier infraestructura. Gracias por dedicarme unos minutos. Hasta la próxima, cuídate.

Hola, soy Alex de DEV STORIES DOT EU. Ecosistema OpenAPI y Swagger, episodio 16 de 19. La documentación de tu API tarda diez segundos en cargar, y cada vez que un ingeniero quiere mostrar un endpoint específico a un compañero, tiene que escribir instrucciones a mano sobre cómo hacer scroll hacia abajo para encontrarlo. Los ajustes por defecto están para cambiarlos. Vamos a retocar la interfaz para que tus desarrolladores encuentren exactamente lo que necesitan en milisegundos. Todo esto va de personalizar Swagger UI. Antes de tocar nada, tenemos que marcar un límite claro. Los ajustes de los que hablamos no van dentro de tu documento de especificación OpenAPI. Son configuraciones de runtime. Estás modificando la interfaz que renderiza el documento, no el documento en sí. Puedes inyectar estos parámetros de dos maneras. Si alojas tú mismo los archivos de la UI, le pasas un objeto de configuración al constructor de Javascript de Swagger UI cuando carga la página web. Si usas la imagen oficial de Docker de Swagger UI, le pasas exactamente estas mismas propiedades directamente al contenedor como variables de entorno. El ajuste más fundamental le dice a la interfaz dónde encontrar tu spec. Si tienes una sola API, usas el parámetro llamado url, en singular, y le pasas un string con la ruta. Pero si tienes una arquitectura de microservicios con varias APIs distintas, usas el parámetro urls, en plural. Le pasas un array que contiene objetos, cada uno con un nombre y un enlace. Esto genera automáticamente un menú desplegable en la barra superior de la interfaz, permitiendo al usuario cambiar entre diferentes definiciones de API sin problemas. Ahora, imagina una API empresarial enorme con cientos de rutas y modelos de datos complejos. Si Swagger UI intenta renderizar todo eso en pantalla a la vez, el navegador se quedará colgado. El parámetro que controla esto es docExpansion. Por defecto, está configurado con la palabra list, que expande todos los tags de nivel superior pero oculta los detalles de la operación. Puedes cambiarlo a full, que expande absolutamente todo en la página. Sin embargo, para ahorrar tiempo de carga en una API gigante, te interesa configurar docExpansion a none. Esto fuerza a que la interfaz cargue completamente colapsada. Ahorra muchísima memoria y se renderiza al instante, dejando que el usuario abra solo lo que realmente necesita. Una vez que el usuario encuentra lo que necesita, querrá compartirlo. Por defecto, hacer clic en las operaciones en Swagger UI no cambia la barra de direcciones del navegador. Si configuras el parámetro deepLinking a true, la interfaz añade un fragmento hash a la URL cada vez que un usuario expande un endpoint o un tag. Tus desarrolladores pueden copiar esa URL exacta y enviársela a un compañero, llevándolo directamente a una operación específica en lugar de al principio de la página. Aquí está la clave. Si tu documentación existe principalmente para actuar como un sandbox, quieres reducir la fricción. Normalmente, un usuario tiene que hacer clic en un botón llamado Try it out en una operación para desbloquear los campos de entrada. Si configuras el flag tryItOutEnabled a true, esos campos de entrada están activos en el momento en que se expande la operación. El usuario simplemente puede escribir y ejecutar sin ese clic extra. Personalizar Swagger UI en runtime te da el poder de adaptar la experiencia de la documentación en torno a la intención del usuario, transformando un renderizado genérico en una herramienta de alto rendimiento hecha a medida para tu equipo. Gracias por escuchar. Cuidaos todos.

Hola, soy Alex de DEV STORIES DOT EU. Ecosistema OpenAPI y Swagger, episodio 17 de 19. Escribir specs de OpenAPI a mano en un editor de texto estándar es una pesadilla de typos y corchetes mal alineados. Necesitas un entorno que te grite en el milisegundo en que indentes mal un path. Eso es exactamente lo que te da diseñar con Swagger Editor. Swagger Editor no es solo una caja de texto. Es un Entorno de Desarrollo Integrado creado específicamente para el estándar OpenAPI. Su función principal es ayudarte a diseñar, definir y documentar tu API desde cero. La interfaz está dividida. El lado izquierdo tiene tu código YAML o JSON en crudo. El lado derecho muestra la documentación interactiva renderizada. Aquí está la clave. El editor valida tu sintaxis contra la especificación OpenAPI en tiempo real. Si escribes mal el nombre de un objeto u olvidas un campo obligatorio, marca el error al instante, diciéndote exactamente qué línea está rota. No tienes que ejecutar un build script aparte para descubrir que tu indentación está mal. Tenemos que aclarar algo sobre las versiones. El Swagger Editor clásico, conocido como versión 4, es una herramienta legacy. Soporta totalmente OpenAPI 2.0 y 3.0. No está construido de forma nativa para OpenAPI 3.1.0. Si pegas una spec 3.1.0 en el editor clásico, fallará la validación. Para las specs 3.1.0 modernas, tienes que pasarte a Swagger Editor Next, que veremos en el episodio final. Pero para el trabajo estándar con 3.0, el editor clásico sigue profundamente integrado en muchos workflows. Puedes usar el editor clásico directamente en tu navegador sin instalar nada. Sin embargo, pegar diseños de APIs propietarias en una web pública es una forma rápida de enfadar a tu equipo de seguridad. Aquí es donde entra en juego la ejecución local. Puedes ejecutar Swagger Editor localmente en tu propia máquina. Puedes instalarlo usando npm haciendo pull del paquete swagger-editor y arrancando un servidor local. Un enfoque aún más limpio es usar Docker. Haces pull de la imagen swaggerapi barra swagger-editor, y levantas un contenedor mapeado a tu puerto local. Esto ejecuta exactamente el mismo editor visual por completo en tu máquina. Este setup permite a los equipos diseñar de forma segura detrás de un firewall corporativo sin exponer specs no publicadas a la internet pública. Toda la validación en tiempo real ocurre localmente. Como el editor proporciona feedback visual instantáneo, diseñas más rápido. Mapeas tus paths, defines tus modelos de datos y verificas inmediatamente que la documentación resultante tenga sentido. Detectas errores estructurales durante la fase de diseño, mucho antes de escribir la lógica de tu backend. Si estos episodios te resultan útiles, puedes apoyar el programa buscando DevStoriesEU en Patreon. El aspecto más valioso del editor es la confianza inmediata que proporciona; una spec sin errores en la pantalla garantiza que tus herramientas downstream funcionarán sin problemas. Eso es todo por este episodio. ¡Gracias por escuchar, y sigue construyendo!

Hola, soy Alex de DEV STORIES DOT EU. Ecosistema OpenAPI y Swagger, episodio 18 de 19. Has dedicado horas a diseñar la especificación perfecta. Ahora, observa cómo escribe miles de líneas de código de servidor para ti en tres segundos. Esa es la recompensa de automatizar con Swagger Codegen. Primero, debemos aclarar una trampa de versionado común. Swagger Codegen versión dos solo admite especificaciones antiguas de Swagger 2.0. Si utilizas el estándar moderno OpenAPI 3.0, debes usar Swagger Codegen versión tres. Este episodio se centra exclusivamente en la versión tres. Swagger Codegen es un motor basado en plantillas que lee tu documento OpenAPI y genera automáticamente el código de la aplicación. Traduce tus archivos de diseño en clases, interfaces y operaciones de red reales. Esta es la máxima recompensa del desarrollo design-first. En lugar de escribir a mano cientos de archivos de boilerplate para el routing HTTP, el parsing de parámetros y los modelos de objetos, dejas que la máquina se encargue del trabajo repetitivo. El generador produce dos tipos principales de código. Primero, crea SDKs de cliente. Si necesitas un cliente Python, JavaScript o Go para hablar con tu API, Codegen crea una librería lista para usar. El paquete del cliente gestiona automáticamente las peticiones HTTP, el formato de URL y el parsing de respuestas. Los desarrolladores frontend u otros equipos de microservicios pueden simplemente importar esta librería generada y llamar a los métodos de forma nativa en lugar de crear a mano las peticiones de red. Segundo, genera stubs de servidor. Un stub de servidor es el esqueleto estructural de tu aplicación backend. Incluye el routing de la API, los modelos de datos y las capas de validación de entrada. Lo conecta todo para que el servidor pueda iniciarse y escuchar tráfico inmediatamente. El código generado intercepta las peticiones HTTP entrantes, valida el payload contra tu schema OpenAPI y pasa los datos limpios a una función vacía. Tu único trabajo como desarrollador es rellenar esas funciones vacías con tu lógica de negocio real, como consultas a la base de datos o cálculos. Vamos a ver cómo se ejecuta esto en la práctica. Swagger Codegen se suele ejecutar mediante una interfaz de línea de comandos utilizando un archivo jar de Java. Abres tu terminal y ejecutas el comando Java con el flag guion jar, apuntando al archivo swagger-codegen-cli punto jar. Le pasas el comando generate. A continuación, proporcionas tres flags esenciales. Usas guion i para especificar tu archivo de entrada, como openapi punto yaml. Usas guion l para configurar tu lenguaje y framework de destino. Por ejemplo, al pasar spring, le indicas a la herramienta que construya una aplicación Java Spring Boot. Finalmente, usas guion o para especificar el directorio de salida. Ejecutas el comando. En pocos segundos, la herramienta parsea la especificación. Mapea cada string, integer y array definido en tu documento OpenAPI a los tipos nativos equivalentes en Java. Se apoya en una librería de plantillas de lógica preconstruidas para el framework de destino para unir estos tipos. El resultado es una estructura de directorios completa, llena de controladores, archivos de configuración y clases de datos. Puedes compilar ese directorio de salida de inmediato, iniciar el servidor y hacer peticiones correctamente a los endpoints que diseñaste. Aquí está la clave. La generación de código no solo ahorra tiempo al principio. Al derivar la estructura de tu servidor y tus librerías de cliente directamente desde el mismo archivo OpenAPI, garantizas que tu implementación coincida perfectamente con tu contrato, reduciendo a cero los errores de integración entre equipos. Eso es todo por este episodio. Gracias por escuchar, ¡y sigue programando!

Hola, soy Alex de DEV STORIES DOT EU. OpenAPI y el ecosistema Swagger, episodio 19 de 19. Las APIs REST ya no son la única forma en la que se comunican los sistemas. Es hora de tener una herramienta que entienda Kafka y las arquitecturas event-driven tan bien como HTTP. Esa herramienta es Swagger Editor Next. También conocida como versión 5, es una reconstrucción completa de la interfaz estándar con la que quizás ya estés familiarizado. El Swagger Editor clásico está muy ligado a las APIs HTTP síncronas y a técnicas de renderizado más antiguas. Funciona bien para OpenAPI 3.0, pero puede congelarse o tener lag al validar archivos excepcionalmente grandes. Swagger Editor Next reemplaza esa infraestructura obsoleta. Está construido completamente sobre un stack moderno de React y Webpack. Esta es la parte que importa. El input de texto subyacente ahora funciona con Monaco Editor. Es exactamente la misma tecnología que mueve Visual Studio Code. Como se basa en Monaco, Swagger Editor Next maneja archivos de especificación enormes sin tirones. Ofrece un syntax highlighting robusto, detección inmediata de errores y una validación precisa a nivel de línea que simplemente supera a la versión clásica. A efectos prácticos, estás escribiendo en un IDE ligero en lugar de en un formulario web. Eso en cuanto al motor. ¿Qué pasa con las especificaciones en sí? Swagger Editor Next trae dos grandes capacidades nativas. Primero, soporta OpenAPI 3.1.0 out of the box. Esta versión específica de OpenAPI se alinea completamente con JSON Schema, lo que significa que puedes construir modelos de datos y componentes reutilizables mucho más complejos de lo que podías en la versión 3.0. Segundo, Swagger Editor Next renderiza de forma nativa las especificaciones de AsyncAPI. Este es el camino definitivo a seguir para los desarrolladores que manejan microservicios event-driven junto con las APIs tradicionales. AsyncAPI usa una estructura muy similar a OpenAPI, pero en lugar de definir paths HTTP y requests GET, documenta message brokers, topics y eventos asíncronos. Para ver cómo funciona esto en la práctica, fíjate en una red de smart city que gestiona el alumbrado público. Si solo tuvieras herramientas para REST, podrías intentar forzar un endpoint HTTP POST para representar un stream constante de datos de sensores. Con Swagger Editor Next, simplemente escribes un documento AsyncAPI. Defines un channel llamado smart-city-streetlights. Asignas Kafka como protocolo. Luego, especificas una operación publish que detalla la estructura JSON exacta que emite el sensor cuando se enciende una luz. A medida que escribes tu especificación en el lado izquierdo de la pantalla, el Monaco Editor valida la sintaxis de AsyncAPI. En el lado derecho, la interfaz renderiza un documento visual estructurado e interactivo. Muestra claramente los topics de Kafka, los payloads esperados de los mensajes y los headers del protocolo. Ya no necesitas toolchains separadas para tus APIs síncronas y tus microservicios event-driven. El ecosistema ha evolucionado para manejar ambos simultáneamente. El cambio hacia los eventos asíncronos no significa empezar de cero con tu documentación; solo requiere un editor moderno capaz de leer esos nuevos estándares. Como esto pone fin a nuestra serie, tómate un momento para leer la documentación oficial, cargar Swagger Editor Next e intentar modelar un topic de Kafka tú mismo. Si tienes una idea para una serie completamente nueva, visita devstories dot eu y cuéntanoslo. Eso es todo por esta vez. ¡Nos vemos en la próxima!