Spring GDS 25 Aniversario
Una empresa de logística que envía a 190 países construyó algo para enviarse a sí misma.
OpenAPI (Swagger)
¿Qué es OpenAPI?
OpenAPI es una forma estándar y legible por máquinas de describir una API REST. Un solo fichero, escrito en YAML o JSON, enumera cada endpoint, los parámetros que reciben, la forma de cada petición y respuesta, la autenticación que requieren y los errores que pueden devolver. Swagger era el nombre original. Cuando la especificación se donó a la Linux Foundation pasó a llamarse OpenAPI, y el nombre Swagger se refiere ahora a las herramientas construidas a su alrededor.
La idea es una única fuente de verdad que tanto humanos como máquinas puedan leer. A partir de un solo documento OpenAPI puedes generar documentación interactiva, SDKs de cliente en una docena de lenguajes, stubs de servidor, servidores mock y pruebas de contrato. Dos equipos pueden acordar primero la especificación y luego construir el frontend y el backend en paralelo contra ella. Una integración de pagos, por ejemplo, puede conectarse y probarse contra un mock generado mucho antes de que el servicio real esté listo.
Hay dos formas de trabajar. Design-first significa que escribes la especificación a mano y el código la sigue. Code-first significa que anotas tu código y la especificación se genera a partir de él. El design-first mantiene el contrato honesto, porque la API se acuerda antes de que nadie se comprometa con una implementación. Sea como sea, la especificación deja de ser documentación que se queda obsoleta y se convierte en aquello contra lo que se contrasta el sistema.
OpenAPI en Dallonses
Trabajamos API-first, y OpenAPI es como hacemos concreta esa promesa. En la mayoría de proyectos la especificación existe antes que los endpoints. Acordamos el contrato con el cliente y sus otros proveedores, generamos el mock y la documentación, y dejamos que los equipos de frontend y backend avancen en paralelo sin bloquearse. Cuando llega la implementación real, las pruebas de contrato la contrastan contra la misma especificación, así la API que se publica coincide con la que todos firmaron.
Para el trabajo de integración de API, un documento OpenAPI claro marca la diferencia entre un traspaso limpio y semanas de adivinanzas. Entregamos a los clientes una especificación que sus propios ingenieros pueden leer, conectar a sus herramientas y en la que pueden confiar. Eso es lo que compra un enfoque de desarrollo API-first: sistemas que se conectan con limpieza porque el contrato se puso por escrito y se respetó, no se describió en un hilo cualquiera.
¿Construyes una API en la que otros equipos tienen que confiar y conectarse? Especifiquémosla bien.
Servicios relacionados
Trabajos relacionados
Vizitio
Convertir una marca en un negocio que funciona.
Access Ticket
Medio millón de personas. Una app. Cero caos.
¿Listo para trabajar juntos?
Reservar una reunión
