Prueba gratis Solicitar demo
View all

¿Qué es Open API? Ventajas, Desventajas & Ejemplos

Category: API Documentation

Last updated on Feb 12, 2025

¿Qué es OpenAPI?

Según SmartBear, la empresa matriz de Swagger:

La especificación de OpenAPI (OAS) define una interfaz estándar e independiente del lenguaje para las API RESTful que permite tanto a humanos como a computadoras descubrir y comprender las capacidades del servicio sin acceso al código fuente, la documentación o mediante la inspección del tráfico de red..«

Eso es una mentira. Vamos a dividir la descripción de SmartBear en partes más pequeñas:

1.“…define un… estándar:

La especificación OpenAPI define la estructura de una API que también describe la API.

2. “…interface agnóstica a APIs RESTful…”:

  • Las APIs REST usan el protocolo HTTP para la transmisión de datos. Este protocolo permite interactuar con plataformas y sistemas escritos en diferentes lenguajes de programación.
  • OpenAPI se ocupa únicamente de las APIs RESTful y no de otros tipos de APIs.

3.“…que permite a los humanos y a las computadoras descubrir y entender las capacidades del servicio…”:

  • Los seres humanos pueden leer la documentación generada directamente a partir de la definición de la OEA de una API.
  • Un cliente entiende cómo puede enviar solicitudes y cómo los servidores API responden a esas peticiones basándose en la definición de la API.

4. “…sin acceso al código fuente, a la documentación o a través de la inspección del tráfico de la red.”

Con OpenAPI, la aplicación cliente y el servidor API están separados. La definición de la API de un servicio define cómo los clientes pueden interactuar con él sin la necesidad de que el cliente lea su código fuente.

En resumen, OpenAPI es una especificación de API RESTful que describe las API que se ajustan a la arquitectura RESTful. Una especificación proporciona una interfaz para permitir que los humanos y las computadoras entiendan una API y cómo interactuar con ella.

Historia de la OpenAPI

Las orígenes de OpenAPI comienzan con el ingeniero Tony Tam de la empresa Wordnik en 2009. Tony creó una especificación (llamada Swagger en ese momento) que describiría el diccionario en línea de Wordnik JSON API.

Swagger sufrió varias iteraciones de Tony en los siguientes años. No obstante, Swagger 2.0 vio un aumento en la adopción de la especificación y desencadenó la creación de herramientas para analizar la especie.

En 2015, SmartBear adquirió Swagger. SmartBear es la empresa que actualmente es propietaria de Swagger. La especificación Swagger fue renombrada “OpenAPI” para reflejar la nueva iniciativa OpenAPI. Este renombrado es la razón por la que “Swagger” se confunde con el estándar “OpenAPI”.

En ese momento, un grupo de empresas reconoció que la industria necesitaba una forma neutral y estandarizada de describir las API. La industria necesitaba proporcionar “mejores prácticas” a la industria y supervisar las actualizaciones de OpenAPI con el tiempo.

Estas compañías establecen la Iniciativa OpenAPI como un programa de gobernanza bajo la Fundación Linux que mantiene el estándar OpenAPI y proporciona orientación práctica. Las empresas fundadoras que formaron la iniciativa OpenAPI fueron CapitalOne, PayPal, SmartBear, IBM, 3Scale, Google, Apigee, Intuit, Microsoft, and Restlet. Desde entonces, el número de empresas que participan en la iniciativa ha aumentado considerablemente.

El Comité Directivo Técnico ahora administra OpenAPI y continúa lanzando nuevas versiones basadas en retroalimentación comunitaria.

¿Por qué OpenAPI es un estándar popular?

Hay varias especificaciones disponibles que describen las API RESTful. OpenAPI es uno de los más conocidos y ampliamente utilizados. Los otros dos formatos utilizados para API REST son RAML y API Blueprint. Más adelante cubriremos las ventajas y desventajas de OpenAPI. Mientras que OpenAPI puede considerarse el estándar de la industria, al final, muchas veces las empresas eligen el formato que mejor se adapta a sus necesidades.

Así que esto nos lleva a la pregunta, si hay varios formatos disponibles para describir APIs REST, ¿por qué OpenAPI es tan especial? Un factor clave para por qué OpenAPI es tan popular es su adopción. Una mayor adopción conduce a más apoyo comunitario, herramientas sólidas y una gobernanza más efectiva.

Una empresa puede utilizar la especificación OpenAPI por su portabilidad y simplicidad. OpenAPI es «agnóstica» y define un lenguaje común para la comunicación cliente-servidor. Es altamente compatible con sistemas escritos en diferentes lenguajes de programación. OpenAPI también es muy legible tanto para humanos como para computadoras y cuenta con el apoyo de una comunidad grande y creciente.

Otro formato popular es RAML, un lenguaje de modelado de API centrado en la definición y el diseño de la API (aunque se pueden diseñar APIs con OpenAPI). Puede parecer que las características de RAML empequeñecen  a OpenAPI. Tiene la ventaja de ser jerárquica y apoyar la herencia del modelo de datos. Sin embargo, RAML no es tan ampliamente adoptado como OpenAPI. Mientras que RAML tiene una comunidad dedicada, tiene menos apoyo comunitario. RAML tiene herramientas, pero hay algunas indicaciones que las últimas versiones carecen del soporte necesario.

Además de RAML, API Blueprint es otra alternativa a OpenAPI. API Blueprint se centra en la documentación clara con base en el formato markdown y no en JSON (como OpenAPI) o YAML (como OpenAPI y RAML). Debido a su baja adopción, el API Blueprint carece de soporte comunitario y herramientas robustas para OpenAPI. Integrar API Blueprint en todo tu ciclo de vida API es difícil porque su único enfoque es la documentación.

En resumen, OpenAPI es el estándar más popular para describir las APIs. Aunque tiene desventajas, es probable que OpenAPI crezca en adopción mientras que la viabilidad a largo plazo de otros tipos de especificaciones es incierta.

¿Cómo  OpenAPI define una API?

Piensa en un documento de especificación heredado que puedes leer en formato Microsoft Word (.docx). Este documento de especificación heredada proporciona el amplio contexto de un sistema y describe sus componentes e interacciones con otros sistemas.

La estructura de las especificaciones heredadas varía a menudo. Una especificación de API, como OpenAPI, está estrictamente estructurada. Si una especificación API se ajusta a otro formato, como RAML o Plano de API, la documentación tiene una estructura que se adhiere a ese formato.

Volviendo a cómo OpenAPI define una API, a menudo escucharás «especificación» y «definición» utilizadas sinónimamente. Una especificación API «define» una API. Al leer una especificación API, aprendes sobre los tipos de solicitudes que puedes enviar y las respuestas que esperas recibir de la API. Además, la especificación describe las opciones disponibles que afectan a la información retornada. Como una especificación heredada, aprendes sobre un sistema, sus componentes y sus interacciones.

Otra diferencia entre las especificaciones heredadas y las especificaciones API es que las especificaciones API son dinámicas. Cuando el código fuente subyacente de una API cambia, la documentación se actualiza. Los documentos de especificación antiguos requieren actualizar manualmente documentos de Word cada vez que el sistema cambia.

Formato OpenAPI

Antes de entender la estructura de una especificación OpenAPI, debe entender el formato de un documento OpenAPI. A diferencia de las especificaciones heredadas escritas en Word, el formato de OpenAPI es JSON. Aunque discutir los matices de JSON está fuera de alcance para este blog, piensa en JSON como una forma de representar los datos de una API como pares clave-valor.

Por ejemplo, en especificaciones antiguas, escribiría el título de una especificación (incluyendo el nombre del sistema) usando un estilo Título en la página de portada. Para escribir el título de una especificación OpenAPI, por otro lado, se debería escribir el título como un par clave-valor JSON.

Ahora, piensa en toda la información sobre una API. Sus métodos, operaciones, respuestas, etc. Imagine todas estas propiedades documentadas en una serie de estos pares clave-valor que siguen la estructura OpenAPI.

Nota: Mientras JSON es el formato estándar para OpenAPI, Es posible representar OpenAPI en YAML más simple (un acrónimo que significa YAML no es un lenguaje marcado).

título de la especificación

Tipos de datos

Como un objeto JSON, la especificación OpenAPI soporta tipos de datos definidos en la especificación más amplia del JSON Schema. Las primitivas incluyen enteros, números, booleanos y cadenas. Puede declarar el formato de un tipo de datos usando el formato de propiedad del modificador. Por ejemplo, puede declarar un entero como formato int32 o int64, un número como flotante o doble, o una cadena como binario, datos, fecha-hora o formato de contraseña. OpenAPI también soporta modelos (objetos) definidos en la especificación JSON más amplia como objetos de Schema.

Es importante señalar que JSON es el formato principal que utilizan las APIs REST para enviar y recibir información.

Estructura

Hasta ahora, entendemos que:

  • Una especificación OpenAPI es un objeto JSON.
  • Las propiedades de una API son un conjunto de pares clave-valor.
  • Los valores son tipos de datos definidos por la especificación JSON más amplia.

Ahora es el momento de discutir la estructura de OpenAPI.

Como se mencionó anteriormente, un documento OpenAPI está estrictamente estructurado. Objetos o matrices de objetos agrupan pares clave-valor relacionados. Los objetos de alto nivel de una especificación OpenAPI son como los capítulos de un documento de especificación heredada.

A continuación hay una plantilla OpenAPI con secciones colapsadas para mostrar la estructura general. Cada sección tiene propiedades, o pares clave-valor, que proporcionan metadatos sobre la API.

Plantilla API con estructura

El nivel superior de OpenAPI, indicado por los primeros conjuntos de corchetes, se llama el «objeto del documento» porque contiene todas las propiedades de OpenAPI.

Aunque los documentos OpenAPI deben ajustarse a una estructura básica, OpenAPI ofrece cierta flexibilidad. Algunas de las secciones de alto nivel son necesarias, mientras que otras no. Notará que las especificaciones de OpenAPI para diferentes APIs pueden parecer ligeramente diferentes.

Un documento OpenAPI puede contener las siguientes secciones:

  • Openapi – Un campo obligatorio que define la versión especificada de OpenAPI de la API. Las herramientas usan el número de versión para analizar la especificación OpenAPI para generar documentación, por ejemplo.
  • Info – Un campo obligatorio que contiene metadatos. Las herramientas pueden aprovechar los metadatos de diferentes maneras.
  • Servidores – Un array de objetos del servidor. Cada objeto del servidor contiene los detalles de conexión a un servidor. Este objeto contiene la URL del servidor y una descripción del servidor.
  • Rutas – Un objeto requerido que contiene las rutas relativas a los extremos separados de la API. Una ruta dada tiene operaciones disponibles para interactuar con la API como POST, GET, PUT o DELETE.
  • Componentes – un objeto que contiene esquemas reutilizables para cuerpos de solicitud, esquemas de respuesta y esquemas de seguridad. Los esquemas en esta sección son referenciados en ciertas partes de la especificación, como el objeto de la ruta, usando la etiqueta $ref.
  • Seguridad – un objeto que declara el tipo de esquema de seguridad autorizando peticiones. Un objeto de seguridad es definido globalmente o anulado por operaciones individuales (sobreescritura del esquema de seguridad).
  • Etiquetas – un objeto que contiene metadatos. Las herramientas que analizan la especificación pueden aprovechar este objeto. Por ejemplo, puedes especificar el orden que desea que cada recurso API se muestra en la documentación de tu API (en lugar de en orden alfabético).
  • ExternalDocs – un objeto que proporciona enlaces a documentación adicional. Puedes usar este objeto para añadir un enlace a tus guías de usuario.

Schemas

En la parte inferior de su documentación API, hay típicamente una sección de Schemas que corresponde a los esquemas descritos en la sección de componentes de la definición de la API.

Esta sección es un glosario rápido para cuando el lector necesita ver esquemas generales en el contexto más amplio de la API (no su uso en determinadas operaciones). Los esquemas son objetos que contienen propiedades/metadatos.

La siguiente sección de esquemas para el Swagger Petstore muestra esquemas específicos. Order es un esquema que representa un pedido realizado para una mascota en la Tienda de Swagger. Cada pedido tiene sus metadatos, incluyendo su Id, la fecha de envío y el estado de la orden.

esquema amplio de especificaciones

OpenAPI: puntos fuertes

OpenAPI tiene las siguientes ventajas:

  • Clara documentación – OpenAPI es conocida por su documentación fácil de leer para humanos y computadoras.
  • Idioma agnóstico – Los clientes pueden interactuar con servidores API sin conocer la implementación del servidor. Otros formatos como Plano API requieren código de terceros en el servidor y no proporcionan ninguno de este código para usted.
  • Gobernanza – La iniciativa OpenAPI mantiene el estándar OpenAPI y es moderada por líderes de la industria.
  • Adopción amplia – OpenAPI es el formato más popular para describir APIs REST. El alcance de su adopción indica que OpenAPI está aquí para el largo plazo. Una especificación, como el Plano de API, sufre de una falta de adopción.
  • Herramientas robustas: Al ser el formato más ampliamente soportado, en la actualidad proliferan las herramientas que aprovechan OpenAPI para generar documentación, realizar pruebas, etc. Otras especificaciones carecen del soporte y mantenimiento de OpenAPI para herramientas.

OpenAPI: puntos débiles

Cada tipo de especificación tiene sus fuerzas y debilidades. Aquí, nos centraremos en las desventajas de OpenAPI en comparación con su rival más cercano, RAML.

Menos útil para el diseño y planificación de la API

Puede adoptar un enfoque “spec-first” para el design de una API basada en OpenAPI. Este enfoque implica escribir la especificación OpenAPI para una API “a mano” o usar una herramienta de design. Usando este enfoque, diseñas una especificación de API y luego usas la especificación como un “contrato” al construir la API. Lo contrario de “spec-first” es utilizar OpenAPI para generar documentación sin usarla como una herramienta de design.

Mientras que el enfoque «spec-first» tiene muchas ventajas, OpenAPI normalmente no viene antes del desarrollo de API.

La estructura jerárquica de RAML puede ser más adecuada para ser una herramienta de design y planificación. Como tal, RAML puede soportar el método “spec-first” más que REST. Al final, RAML es marcada como una herramienta de “modelado de datos” y API “descripción”, mientras que Swagger es la última. El modelo jerárquico de RAML se discute más en la siguiente sección.

No jerárquico

Uno de los conceptos básicos para los estándares de definición de API como OpenAPI y RAML es la capacidad de crear objetos de datos y relacionarlos juntos. OpenAPI utiliza esquemas para este propósito y soporta los tipos de datos incorporados de JSON. RAML utiliza un sistema de tipos para guardar las propiedades asociadas y promover la reutilización a través de la especificación. También soporta los mismos tipos de datos incorporados que OpenAPI.

OpenAPI no tiene una estructura jerárquica “verdadera”. ¿Qué quieres de una estructura jerárquica que describa tu API? Idealmente, quieres un sistema para asociar tus modelos de datos que es:

  • fácilmente legible/comprensible
  • permite definir relaciones entre modelos de datos usando la herencia
  • reduce la repetición de propiedades compartidas
  • maximiza la reusabilidad del código

El sistema de tipo RAML se presta a ser un sistema más jerárquico que el REST. Según la lectura de RAML en GitHub, El uso por parte de RAML de «tipos de recursos y rasgos minimiza la repetición en un RESTful diseño API y promueve la consistencia dentro y a través de APIs. A continuación discutiremos más detalladamente el sistema de tipos de RAML.

No soporta la herencia del modelo de datos

Los tipos de objetos de RAML pueden heredar otros tipos de objetos. Aunque los esquemas OpenAPI pueden “referenciar” esquemas, técnicamente no soportan la herencia como lo hace RAML. Digo “técnicamente»” porque puedes enlazar un esquema a otro usando una referencia de esquema (la etiqueta $ref). Sin embargo, RAML va un paso más allá. Puede establecer relaciones entre modelos de datos y evitar la repetición de propiedades compartidas. Con OpenAPI, los esquemas no están asociados entre sí de forma jerárquica como con RAML. Los tipos RAML tienen una herencia “verdadera”, donde se pueden establecer relaciones padre-hijo entre modelos de datos.

No es una herramienta «visual»

El uso de los tipos RAML como modelos de datos lo hace más visual y fácil de leer que OpenAPI. Puedes ver fácilmente la relación entre los tipos y sus propiedades compartidas.

RAML, como una herramienta más visual, promueve la planificación a largo plazo para cosas como respuestas de servidor simulado, consolas API y más. También puede anticipar y planificar futuras mejoras de la API usando RAML.

Falta de apoyo para otras arquitecturas

OpenAPI sólo puede describir APIs RESTful. RAML tiene el beneficio añadido de soportar otras arquitecturas además de REST, tales como RPC o SOAP, siempre y cuando utilicen el protocolo HTTP. La flexibilidad de RAML le permite utilizarla como herramienta de documentación para arquitecturas además de REST.

Ejemplo de OpenAPI – Swagger Petstore

La mejor manera de aprender OpenAPI es tomar un enfoque práctico. Ciertas herramientas le permiten editar las especificaciones de OpenAPI y luego generar documentación de API. La especificación Swagger Petstore es un ejemplo de documento OpenAPI.

SwaggerUI es una herramienta que analiza una definición de API para generar documentación. SwaggerUI tiene un editor basado en el navegador (se muestra abajo). Puedes experimentar con el editor de SwaggerUI aquí: S editor.swagger.io

Swagger UI examples

En el panel izquierdo, la especificación OpenAPI en formato YAML es visible. Cada vez que hace cambios en la especificación, esos cambios generan nueva documentación en el panel de la derecha. El panel del lado derecho es el documento Swagger generado directamente a partir de la especificación OpenAPI para la Petstore (panel del lado izquierdo). Por ejemplo, cambiar la descripción de una ruta hace que el documento Swagger se actualice con los nuevos cambios.

Si miras la especificación OpenAPI de Swagger a la izquierda, verás todas las secciones descritas en este artículo del blog, incluyendo openapi, info, servidores, caminos, componentes, etiquetas, etc.

Swagger genera un error cuando se desvía de la estructura OpenAPI o introduce algo inválido. El manejo de errores de Swagger refuerza el concepto de que debe adherirse al formato OpenAPI para que la documentación se muestre correctamente. Una vez que te familiarices con el Swagger Petstore, puedes pegar la especificación de otra API en el editor de Swagger para ver cómo se muestra su información en SwaggerUI.

En resumen, Swagger Editor es una gran manera de familiarizarse con cómo escribir definiciones API y cómo las herramientas analizan la especificación para generar documentación.

Lectura adicional

Para obtener documentación más detallada sobre el estándar OpenAPI, lee la documentación oficial de SmartBear para OpenAPI: https://swagger.io/specification/.

También, revisa nuestra guía para lanzar API pública

¿Listo para llevar su documentación API al siguiente nivel? ¡Reserve una demostración con Document360 hoy!

Agenda una Demo
Document360

Preguntas frecuentes

  • ¿Qué es la OpenAPI?

    La OpenAPI (también conocida como API pública) es una interfaz de programación de aplicaciones disponible públicamente que permite a los desarrolladores acceder a una aplicación de software propietaria o a un servicio en línea programáticamente.

  • Una API abierta tiene restricciones de acceso porque está abierta al público y puede ser invocada desde cualquier lugar en el Internet abierto. Una API cerrada, también conocida como API privada, por otra parte, no está disponible en Internet.

  • El estándar OpenAPI (OAS), anteriormente conocido como la especificación Swagger, es un formato para describir, producir, consumir y visualizar los servicios web de RESTful. El estándar REST API describe la estructura y sintaxis.

Related Articles