OpenAPI (OpenAPI Specification, OAS) es un estándar para describir cómo funciona una API REST de una forma estructurada que tanto las personas como otras herramientas pueden entender. Es de código abierto, independiente del lenguaje de programación, y se utiliza para definir API HTTP, especialmente las API REST.
Un archivo OpenAPI, también conocido como documento OpenAPI o especificación OpenAPI, permite a un desarrollador describir una API. Esta especificación también describe cómo usar esta API, incluidos los endpoint disponibles, los parámetros de operación, los métodos de autenticación y otra información. Los documentos OpenAPI están escritos en YAML o JSON, y JSON Schema se utiliza para describir los formatos de datos dentro de una API.
OpenAPI sirve tanto como documentación como contrato de API (en esencia, describe lo que una API debería hacer; no es legalmente vinculante) entre los usuarios y los proveedores de la API. Esencialmente sirve como una fuente única de información que proporciona las instrucciones en un formato estandarizado.
Esta estandarización simplifica el consumo y la integración de API. Permite que tanto los humanos como las computadoras comprendan la función y la estructura de una API determinada sin acceso al código fuente ni necesidad de comprender el funcionamiento interno de la API. También permite a los desarrolladores trabajar con una API, independientemente del lenguaje en el que se haya escrito.
OpenAPI permite generar documentación interactiva a partir de la especificación, eliminando algunos trabajos de documentación repetitivos y ayudando a garantizar que la documentación permanezca actualizada. OpenAPI también permite la generación de SDK de cliente y la generación de código repetitivo adicional automáticamente a partir de la especificación, lo que reduce el error humano y minimiza aún más la carga de trabajo del desarrollador.
Las herramientas que utilizan especificaciones de OpenAPI, incluida Swagger UI, pueden representar una especificación de API en una interfaz interactiva. Esta interfaz no solo ayuda a visualizar la especificación, sino que también permite llamadas reales a la API, directamente desde el navegador mediante la interfaz, con fines de prueba y validación.
Al estandarizar la forma en que se describen las API REST, OpenAPI ayuda a mejorar la interoperabilidad y las herramientas, y respalda las operaciones a lo largo del ciclo de vida de la API. Una especificación sólida y bien mantenida puede ser una herramienta fundamental para implementar una estrategia de API integral, que respalde la integración, la colaboración, la prevención de errores y la gestión de API más sólida.
Como estándar de facto de la industria, OpenAPI proporciona un formato estandarizado, legible por máquinas y ampliamente utilizado para el desarrollo de API.
OpenAPI fue creado originalmente por el desarrollador Tony Tam y se lanzó por primera vez en 2011 con el nombre de Swagger. En ese momento, las especificaciones de API eran a menudo documentos estáticos que requerían una actualización tediosa y con frecuencia estaban desactualizados. La especificación Swagger incluía varias innovaciones en el desarrollo de API, incluido un botón “Try it out” para probar las llamadas reales a la API y en tiempo real.
Swagger puso la documentación en el centro de su enfoque. Esto permitió a los desarrolladores incluir anotaciones en su código fuente. Swagger podría leer estas anotaciones y actualizar la documentación automáticamente, lo que garantiza que la documentación se mantenga al día sin necesidad de realizar tareas de actualización tediosas y repetitivas. Swagger también introdujo un formato para describir las API en JSON legible por máquina, lo que lo hizo independiente del lenguaje: sin importar el lenguaje de un backend, Swagger produciría resultados JSON universales.
Swagger fue adquirido por SmartBear Software en 2015, pasó a llamarse OpenAPI poco después y se donó a la nueva Iniciativa OpenAPI (OAI), bajo el control de la Linux Foundation. La versión actual es OpenAPI 3.1.
La especificación OpenAPI es un documento estandarizado, legible por humanos y máquinas, que define la estructura y la sintaxis de la API.
Todos los documentos de OpenAPI incluyen ciertos componentes y se ajustan a la misma estructura básica, pero algunas especificaciones contienen más información que otras. Como mínimo, una especificación debe incluir
OpenAPI proporciona una única fuente de información para los desarrolladores y consumidores de API, y proporciona características que agregan valor y eficiencia a los proyectos de API.
OpenAPI se creó inicialmente con un gran enfoque en la documentación de las API REST, y ese enfoque sigue siendo su núcleo en la actualidad. La documentación está estandarizada, es interactiva, se actualiza en tiempo real y ofrece un contrato con una única fuente de información.
Existen varias herramientas para leer documentos de OpenAPI y exportar código. Una de esas herramientas es Swagger Codegen, que lee documentos escritos de acuerdo con la especificación OpenAPI.
Swagger Codegen puede producir kits de desarrollo de software (SDK) de código de cliente API, código del lado del servidor (stubs) y páginas de documentación actualizadas y legibles por humanos.
Una de las características más innovadoras de OpenAPI sigue siendo el botón “probarlo”, que permite realizar pruebas y validación en tiempo real directamente desde un navegador.
La interfaz de usuario (IU) de Swagger, una herramienta gratuita de código abierto, habilita una interfaz visual en la que un desarrollador puede enviar solicitudes reales para ayudar a garantizar que respondan como se desea. Esta herramienta facilita la verificación instantánea de que una solicitud funciona correctamente.
OpenAPI se usa comúnmente con plataformas de integración como servicio o iPaaS.
Las plataformas iPaaS utilizan especificaciones OpenAPI para comprender y conectar diferentes aplicaciones en un ecosistema de TI. Cuando las aplicaciones exponen especificaciones de OpenAPI que describen sus API, las plataformas iPaaS pueden usar esta información para descubrir automáticamente endpoints, métodos de autenticación y estructuras de datos. Esta estrategia permite crear integraciones más rápidamente, como por ejemplo, conectar una plataforma de comercio electrónico con un software de contabilidad.
OpenAPI también permite a los desarrolladores de frontend y backend trabajar en paralelo. Es preferible trabajar en paralelo a que, como ocurre a veces, el equipo de frontend se vea obligado a esperar a que el equipo de backend tenga la base de datos en funcionamiento.
Con un contrato OpenAPI, el equipo de frontend puede crear un servidor API simulado que se comporta como uno real, habilitando y optimizando las pruebas antes de que se complete el desarrollo del backend.
La gobernanza de las API (los estándares, políticas y prácticas que dirigen cómo una organización desarrolla y usa las API) es vital para garantizar que las API funcionen perfectamente, de forma coherente y sin repeticiones innecesarias. Debido a que OpenAPI actúa como un contrato entre desarrolladores, la gobernanza y la seguridad se pueden integrar desde el principio.
Tomemos como ejemplo las pasarelas de API, que gestionan tareas como el enrutamiento del tráfico, el monitoreo y la limitación de velocidad. Las pasarelas normalmente pueden consumir especificaciones de OpenAPI y aplicar cualquier límite de tráfico u otras medidas de seguridad establecidas en la especificación.
Lo mismo se aplica a las reglas de seguridad. Una especificación de OpenAPI permite a los desarrolladores declarar requisitos de seguridad (como el uso de OAuth 2.0 y claves de API), y estos requisitos se pueden aplicar en sentido descendente (quizás mediante una pasarela). Describir las características de seguridad en un contrato de API ayuda a garantizar que los desarrolladores no implementen esquemas de seguridad no compatibles.
OpenAPI puede fortalecer la gestión de API, el proceso escalable de crear, publicar y gestionar conexiones API, de varias maneras. Por ejemplo, debido a que las especificaciones de OpenAPI son legibles por máquina y están estandarizadas, el software de catálogo y portal puede indexarlas automáticamente. Esta estandarización hace que las API sean más fáciles de encontrar y comprender en toda la organización. Esta capacidad de descubrimiento ayuda a evitar que los equipos construyan API duplicadas sin saberlo.
OpenAPI también admite una gestión y gobernanza coherentes al hacer que los estándares organizacionales sean explícitos y susceptibles de validación automática. Los equipos pueden definir requisitos, como convenciones de versiones, formatos de respuesta de error o patrones de nomenclatura, directamente en la especificación o junto a ella. Debido a que estas expectativas están documentadas en un formato estandarizado, se pueden validar automáticamente con nuevas API a medida que se agregan.
Esta validación reduce la dependencia de la revisión manual y ayuda a garantizar que las API sigan siendo coherentes a medida que crece la cartera de una organización.
Desarrolle, gestione, proteja y socialice perfectamente todos sus tipos de interfaz de programación de aplicaciones (API), dondequiera que residan.
Potencie su negocio a través de una conectividad y automatización perfectas con el software de plataforma de integración.
Desbloquee todo el potencial de la nube híbrida en la era de la IA agéntica.
1 “OpenAPI Specification, Version 3.1.1.” swagger.io, 2026