Eso es una mentira. Vamos a dividir la descripci\u00f3n de SmartBear en partes m\u00e1s peque\u00f1as:<\/p>\r\n
1.\u201c\u2026define un\u2026 est\u00e1ndar: <\/strong><\/p>\r\n La especificaci\u00f3n OpenAPI define la estructura de una API que tambi\u00e9n describe la API.<\/p>\r\n 2. \u201c\u2026interface agn\u00f3stica a APIs RESTful\u2026\u201d:<\/strong><\/p>\r\n 3.\u201c\u2026que permite a los humanos y a las computadoras descubrir y entender las capacidades del servicio\u2026\u201d:<\/strong><\/p>\r\n 4. \u201c\u2026sin acceso al c\u00f3digo fuente, a la documentaci\u00f3n o a trav\u00e9s de la inspecci\u00f3n del tr\u00e1fico de la red.\u201d<\/strong><\/p>\r\n Con OpenAPI, la aplicaci\u00f3n cliente y el servidor API est\u00e1n separados. La definici\u00f3n de la API de un servicio define c\u00f3mo los clientes pueden interactuar con \u00e9l sin la necesidad de que el cliente lea su c\u00f3digo fuente.<\/p>\r\n En resumen, OpenAPI es una especificaci\u00f3n de API RESTful<\/a> que describe las API que se ajustan a la arquitectura RESTful. Una especificaci\u00f3n proporciona una interfaz para permitir que los humanos y las computadoras entiendan una API y c\u00f3mo interactuar con ella.<\/p>\r\n Las or\u00edgenes de OpenAPI comienzan con el ingeniero Tony Tam de la empresa Wordnik en 2009. Tony cre\u00f3 una especificaci\u00f3n (llamada Swagger en ese momento) que describir\u00eda el diccionario en l\u00ednea de Wordnik JSON API.<\/p>\r\n Swagger sufri\u00f3 varias iteraciones de Tony en los siguientes a\u00f1os. No obstante, Swagger 2.0 vio un aumento en la adopci\u00f3n de la especificaci\u00f3n y desencaden\u00f3 la creaci\u00f3n de herramientas para analizar la especie.<\/p>\r\n En 2015, SmartBear adquiri\u00f3 Swagger. SmartBear es la empresa que actualmente es propietaria de Swagger. La especificaci\u00f3n Swagger fue renombrada \u201cOpenAPI\u201d para reflejar la nueva iniciativa OpenAPI. Este renombrado es la raz\u00f3n por la que \u201cSwagger\u201d se confunde con el est\u00e1ndar \u201cOpenAPI\u201d.<\/p>\r\n En ese momento, un grupo de empresas reconoci\u00f3 que la industria necesitaba una forma neutral y estandarizada de describir las API. La industria necesitaba proporcionar \u201cmejores pr\u00e1cticas\u201d a la industria y supervisar las actualizaciones de OpenAPI con el tiempo.<\/p>\r\n Estas compa\u00f1\u00edas establecen la Iniciativa OpenAPI como un programa de gobernanza bajo la Fundaci\u00f3n Linux que mantiene el est\u00e1ndar OpenAPI y proporciona orientaci\u00f3n pr\u00e1ctica. Las empresas fundadoras que formaron la iniciativa OpenAPI fueron CapitalOne, PayPal, SmartBear, IBM, 3Scale, Google, Apigee, Intuit, Microsoft, and Restlet. Desde entonces, el n\u00famero de empresas que participan en la iniciativa ha aumentado considerablemente.<\/p>\r\n El Comit\u00e9 Directivo T\u00e9cnico ahora administra OpenAPI y contin\u00faa lanzando nuevas versiones basadas en retroalimentaci\u00f3n comunitaria.<\/p>\r\n Hay varias especificaciones disponibles que describen las API RESTful. OpenAPI es uno de los m\u00e1s conocidos y ampliamente utilizados. Los otros dos formatos utilizados para API REST son RAML y API Blueprint. M\u00e1s adelante cubriremos las ventajas y desventajas de OpenAPI. Mientras que OpenAPI puede considerarse el est\u00e1ndar de la industria, al final, muchas veces las empresas eligen el formato que mejor se adapta a sus necesidades.<\/p>\r\n As\u00ed que esto nos lleva a la pregunta, si hay varios formatos disponibles para describir APIs REST, \u00bfpor qu\u00e9 OpenAPI es tan especial? Un factor clave para por qu\u00e9 OpenAPI es tan popular es su adopci\u00f3n. Una mayor adopci\u00f3n conduce a m\u00e1s apoyo comunitario, herramientas s\u00f3lidas y una gobernanza m\u00e1s efectiva.<\/p>\r\n Una empresa puede utilizar la especificaci\u00f3n OpenAPI por su portabilidad y simplicidad. OpenAPI es \u00abagn\u00f3stica\u00bb y define un lenguaje com\u00fan para la comunicaci\u00f3n cliente-servidor. Es altamente compatible con sistemas escritos en diferentes lenguajes de programaci\u00f3n. OpenAPI tambi\u00e9n es muy legible tanto para humanos como para computadoras y cuenta con el apoyo de una comunidad grande y creciente.<\/p>\r\n Otro formato popular es RAML, un lenguaje de modelado de API centrado en la definici\u00f3n y el dise\u00f1o de la API (aunque se pueden dise\u00f1ar APIs con OpenAPI). Puede parecer que las caracter\u00edsticas de RAML empeque\u00f1ecen\u00a0 a OpenAPI. Tiene la ventaja de ser jer\u00e1rquica 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 \u00faltimas versiones carecen del soporte necesario.<\/p>\r\n Adem\u00e1s de RAML, API Blueprint es otra alternativa a OpenAPI. API Blueprint se centra en la documentaci\u00f3n clara con base en el formato markdown y no en JSON (como OpenAPI) o YAML (como OpenAPI y RAML). Debido a su baja adopci\u00f3n, el API Blueprint carece de soporte comunitario y herramientas robustas para OpenAPI. Integrar API Blueprint en todo tu ciclo de vida API es dif\u00edcil porque su \u00fanico enfoque es la documentaci\u00f3n.<\/p>\r\n En resumen, OpenAPI es el est\u00e1ndar m\u00e1s popular para describir las APIs. Aunque tiene desventajas, es probable que OpenAPI crezca en adopci\u00f3n mientras que la viabilidad a largo plazo de otros tipos de especificaciones es incierta.<\/p>\r\n Piensa en un documento de especificaci\u00f3n heredado que puedes leer en formato Microsoft Word (.docx). Este documento de especificaci\u00f3n heredada proporciona el amplio contexto de un sistema y describe sus componentes e interacciones con otros sistemas.<\/p>\r\n La estructura de las especificaciones heredadas var\u00eda a menudo. Una especificaci\u00f3n de API, como OpenAPI, est\u00e1 estrictamente estructurada. Si una especificaci\u00f3n API se ajusta a otro formato, como RAML o Plano de API, la documentaci\u00f3n tiene una estructura que se adhiere a ese formato.<\/p>\r\n Volviendo a c\u00f3mo OpenAPI define una API, a menudo escuchar\u00e1s \u00abespecificaci\u00f3n\u00bb y \u00abdefinici\u00f3n\u00bb utilizadas sin\u00f3nimamente. Una especificaci\u00f3n API \u00abdefine\u00bb una API. Al leer una especificaci\u00f3n API, aprendes sobre los tipos de solicitudes que puedes enviar y las respuestas que esperas recibir de la API. Adem\u00e1s, la especificaci\u00f3n describe las opciones disponibles que afectan a la informaci\u00f3n retornada. Como una especificaci\u00f3n heredada, aprendes sobre un sistema, sus componentes y sus interacciones.<\/p>\r\n Otra diferencia entre las especificaciones heredadas y las especificaciones API es que las especificaciones API son din\u00e1micas. Cuando el c\u00f3digo fuente subyacente de una API cambia, la documentaci\u00f3n se actualiza. Los documentos de especificaci\u00f3n antiguos requieren actualizar manualmente documentos de Word cada vez que el sistema cambia.<\/p>\r\n Antes de entender la estructura de una especificaci\u00f3n 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\u00e1 fuera de alcance para este blog, piensa en JSON como una forma de representar los datos de una API como pares clave-valor.<\/p>\r\n Por ejemplo, en especificaciones antiguas, escribir\u00eda el t\u00edtulo de una especificaci\u00f3n (incluyendo el nombre del sistema) usando un estilo T\u00edtulo en la p\u00e1gina de portada. Para escribir el t\u00edtulo de una especificaci\u00f3n OpenAPI, por otro lado, se deber\u00eda escribir el t\u00edtulo como un par clave-valor JSON.<\/p>\r\n Ahora, piensa en toda la informaci\u00f3n sobre una API. Sus m\u00e9todos, operaciones, respuestas, etc. Imagine todas estas propiedades documentadas en una serie de estos pares clave-valor que siguen la estructura OpenAPI.<\/p>\r\n Nota:<\/strong> Mientras JSON es el formato est\u00e1ndar para OpenAPI, Es posible representar OpenAPI en YAML m\u00e1s simple (un acr\u00f3nimo que significa YAML no es un lenguaje marcado).<\/p>\r\n Como un objeto JSON, la especificaci\u00f3n OpenAPI soporta tipos de datos definidos en la especificaci\u00f3n m\u00e1s amplia del JSON Schema. Las primitivas incluyen enteros, n\u00fameros, 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\u00famero como flotante o doble, o una cadena como binario, datos, fecha-hora o formato de contrase\u00f1a. OpenAPI tambi\u00e9n soporta modelos (objetos) definidos en la especificaci\u00f3n JSON m\u00e1s amplia como objetos de Schema.<\/p>\r\n Es importante se\u00f1alar que JSON es el formato principal que utilizan las APIs REST para enviar y recibir informaci\u00f3n.<\/p>\r\n Hasta ahora, entendemos que:<\/p>\r\n Ahora es el momento de discutir la estructura de OpenAPI.<\/p>\r\n Como se mencion\u00f3 anteriormente, un documento OpenAPI est\u00e1 estrictamente estructurado. Objetos o matrices de objetos agrupan pares clave-valor relacionados. Los objetos de alto nivel de una especificaci\u00f3n OpenAPI son como los cap\u00edtulos de un documento de especificaci\u00f3n heredada.<\/p>\r\n A continuaci\u00f3n hay una plantilla OpenAPI<\/strong> con secciones colapsadas para mostrar la estructura general. Cada secci\u00f3n tiene propiedades, o pares clave-valor, que proporcionan metadatos sobre la API.<\/p>\r\n El nivel superior de OpenAPI, indicado por los primeros conjuntos de corchetes, se llama el \u00abobjeto del documento\u00bb porque contiene todas las propiedades de OpenAPI.<\/p>\r\n Aunque los documentos OpenAPI deben ajustarse a una estructura b\u00e1sica, OpenAPI ofrece cierta flexibilidad. Algunas de las secciones de alto nivel son necesarias, mientras que otras no. Notar\u00e1 que las especificaciones de OpenAPI para diferentes APIs pueden parecer ligeramente diferentes.<\/p>\r\n Un documento OpenAPI puede contener las siguientes secciones:<\/p>\r\n En la parte inferior de su documentaci\u00f3n API, hay t\u00edpicamente una secci\u00f3n de Schemas que corresponde a los esquemas descritos en la secci\u00f3n de componentes de la definici\u00f3n de la API.<\/p>\r\n Esta secci\u00f3n es un glosario r\u00e1pido para cuando el lector necesita ver esquemas generales en el contexto m\u00e1s amplio de la API (no su uso en determinadas operaciones). Los esquemas son objetos que contienen propiedades\/metadatos.<\/p>\r\n La siguiente secci\u00f3n de esquemas para el Swagger Petstore muestra esquemas espec\u00edficos. Order<\/strong> 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\u00edo y el estado de la orden.<\/strong><\/p>\r\n OpenAPI tiene las siguientes ventajas:<\/p>\r\n Cada tipo de especificaci\u00f3n tiene sus fuerzas y debilidades. Aqu\u00ed, nos centraremos en las desventajas de OpenAPI en comparaci\u00f3n con su rival m\u00e1s cercano, RAML.<\/p>\r\n Puede adoptar un enfoque \u201cspec-first\u201d para el design de una API basada en OpenAPI. Este enfoque implica escribir la especificaci\u00f3n OpenAPI para una API \u201ca mano\u201d o usar una herramienta de design. Usando este enfoque, dise\u00f1as una especificaci\u00f3n de API y luego usas la especificaci\u00f3n como un \u201ccontrato\u201d al construir la API. Lo contrario de \u201cspec-first\u201d es utilizar OpenAPI para generar documentaci\u00f3n sin usarla como una herramienta de design.<\/p>\r\n Mientras que el enfoque \u00abspec-first\u00bb tiene muchas ventajas, OpenAPI normalmente no viene antes del desarrollo de API.<\/p>\r\n La estructura jer\u00e1rquica de RAML puede ser m\u00e1s adecuada para ser una herramienta de design y planificaci\u00f3n. Como tal, RAML puede soportar el m\u00e9todo \u201cspec-first\u201d m\u00e1s que REST. Al final, RAML es marcada como una herramienta de \u201cmodelado de datos\u201d y API \u201cdescripci\u00f3n\u201d, mientras que Swagger es la \u00faltima. El modelo jer\u00e1rquico de RAML se discute m\u00e1s en la siguiente secci\u00f3n.<\/p>\r\n Uno de los conceptos b\u00e1sicos para los est\u00e1ndares de definici\u00f3n de API como OpenAPI y RAML es la capacidad de crear objetos de datos y relacionarlos juntos. OpenAPI utiliza esquemas para este prop\u00f3sito y soporta los tipos de datos incorporados de JSON. RAML utiliza un sistema de tipos para guardar las propiedades asociadas y promover la reutilizaci\u00f3n a trav\u00e9s de la especificaci\u00f3n. Tambi\u00e9n soporta los mismos tipos de datos incorporados que OpenAPI.<\/p>\r\n OpenAPI no tiene una estructura jer\u00e1rquica \u201cverdadera\u201d. \u00bfQu\u00e9 quieres de una estructura jer\u00e1rquica que describa tu API? Idealmente, quieres un sistema para asociar tus modelos de datos que es:<\/p>\r\n El sistema de tipo RAML se presta a ser un sistema m\u00e1s jer\u00e1rquico que el REST. Seg\u00fan la lectura de RAML en GitHub, El uso por parte de RAML de \u00abtipos de recursos y rasgos minimiza la repetici\u00f3n en un RESTful dise\u00f1o API y promueve la consistencia dentro y a trav\u00e9s de APIs. A continuaci\u00f3n discutiremos m\u00e1s detalladamente el sistema de tipos de RAML.<\/p>\r\n Los tipos de objetos de RAML pueden heredar otros tipos de objetos. Aunque los esquemas OpenAPI pueden \u201creferenciar\u201d esquemas, t\u00e9cnicamente no soportan la herencia como lo hace RAML. Digo \u201ct\u00e9cnicamente\u00bb\u201d porque puedes enlazar un esquema a otro usando una referencia de esquema (la etiqueta $ref). Sin embargo, RAML va un paso m\u00e1s all\u00e1. Puede establecer relaciones entre modelos de datos y evitar la repetici\u00f3n de propiedades compartidas. Con OpenAPI, los esquemas no est\u00e1n asociados entre s\u00ed de forma jer\u00e1rquica como con RAML. Los tipos RAML tienen una herencia \u201cverdadera\u201d, donde se pueden establecer relaciones padre-hijo entre modelos de datos.<\/p>\r\n El uso de los tipos RAML como modelos de datos lo hace m\u00e1s visual y f\u00e1cil de leer que OpenAPI. Puedes ver f\u00e1cilmente la relaci\u00f3n entre los tipos y sus propiedades compartidas.<\/p>\r\n RAML, como una herramienta m\u00e1s visual, promueve la planificaci\u00f3n a largo plazo para cosas como respuestas de servidor simulado, consolas API y m\u00e1s. Tambi\u00e9n puede anticipar y planificar futuras mejoras de la API usando RAML.<\/p>\r\n OpenAPI s\u00f3lo puede describir APIs RESTful. RAML tiene el beneficio a\u00f1adido de soportar otras arquitecturas adem\u00e1s 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\u00f3n para arquitecturas adem\u00e1s de REST.<\/p>\r\n La mejor manera de aprender OpenAPI es tomar un enfoque pr\u00e1ctico. Ciertas herramientas le permiten editar las especificaciones de OpenAPI y luego generar documentaci\u00f3n de API. La especificaci\u00f3n Swagger Petstore es un ejemplo de documento OpenAPI.<\/p>\r\n SwaggerUI es una herramienta que analiza una definici\u00f3n de API para generar documentaci\u00f3n. SwaggerUI tiene un editor basado en el navegador (se muestra abajo). Puedes experimentar con el editor de SwaggerUI aqu\u00ed: S editor.swagger.io<\/a><\/p>\r\n En el panel izquierdo, la especificaci\u00f3n OpenAPI en formato YAML es visible. Cada vez que hace cambios en la especificaci\u00f3n, esos cambios generan nueva documentaci\u00f3n en el panel de la derecha. El panel del lado derecho es el documento Swagger generado directamente a partir de la especificaci\u00f3n OpenAPI para la Petstore (panel del lado izquierdo). Por ejemplo, cambiar la descripci\u00f3n de una ruta hace que el documento Swagger se actualice con los nuevos cambios.<\/p>\r\n Si miras la especificaci\u00f3n OpenAPI de Swagger a la izquierda, ver\u00e1s todas las secciones descritas en este art\u00edculo del blog, incluyendo openapi, info, servidores, caminos, componentes, etiquetas<\/strong>, etc.<\/p>\r\n Swagger genera un error cuando se desv\u00eda de la estructura OpenAPI o introduce algo inv\u00e1lido. El manejo de errores de Swagger refuerza el concepto de que debe adherirse al formato OpenAPI para que la documentaci\u00f3n se muestre correctamente. Una vez que te familiarices con el Swagger Petstore, puedes pegar la especificaci\u00f3n de otra API en el editor de Swagger para ver c\u00f3mo se muestra su informaci\u00f3n en SwaggerUI.<\/p>\r\n En resumen, Swagger Editor es una gran manera de familiarizarse con c\u00f3mo escribir definiciones API y c\u00f3mo las herramientas analizan la especificaci\u00f3n para generar documentaci\u00f3n.<\/p>\r\n Para obtener documentaci\u00f3n m\u00e1s detallada sobre el est\u00e1ndar OpenAPI, lee la documentaci\u00f3n oficial de SmartBear para OpenAPI: https:\/\/swagger.io\/specification\/.<\/p>\r\n Tambi\u00e9n, revisa nuestra gu\u00eda para lanzar API p\u00fablica<\/em><\/strong><\/p>\r\n \u00bfListo para llevar su documentaci\u00f3n API al siguiente nivel? \u00a1Reserve una demostraci\u00f3n con Document360 hoy!<\/p>\r\nAgenda una Demo<\/a><\/div>\r\n La OpenAPI (tambi\u00e9n conocida como API p\u00fablica) es una interfaz de programaci\u00f3n de aplicaciones disponible p\u00fablicamente que permite a los desarrolladores acceder a una aplicaci\u00f3n de software propietaria o a un servicio en l\u00ednea program\u00e1ticamente.<\/p>\r\n<\/div>\r\n<\/li>\r\n\t Una API abierta tiene restricciones de acceso porque est\u00e1 abierta al p\u00fablico y puede ser invocada desde cualquier lugar en el Internet abierto. Una API cerrada, tambi\u00e9n conocida como API privada, por otra parte, no est\u00e1 disponible en Internet.<\/p>\r\n<\/div>\r\n<\/li>\r\n\t El est\u00e1ndar OpenAPI (OAS), anteriormente conocido como la especificaci\u00f3n Swagger, es un formato para describir, producir, consumir y visualizar los servicios web de RESTful. El est\u00e1ndar REST API describe la estructura y sintaxis.<\/p>\r\n<\/div>\r\n<\/li>\r\n<\/ul>\r\n<\/div>\r\n<\/div>\r\n<\/div>\r\n\r\n\t
\r\n\t
Historia de la OpenAPI<\/h2>\r\n
\u00bfPor qu\u00e9 OpenAPI es un est\u00e1ndar popular?<\/strong><\/h2>\r\n
\u00bfC\u00f3mo\u00a0 OpenAPI define una API?<\/strong><\/h2>\r\n
Formato OpenAPI <\/strong><\/h2>\r\n
![\"t\u00edtulo](\"https:\/\/document360.com\/wp-content\/uploads\/2022\/12\/title_of_specification.png\")
<\/p>\r\nTipos de datos<\/h2>\r\n
Estructura<\/h2>\r\n
\r\n\t
![\"Plantilla](\"https:\/\/document360.com\/wp-content\/uploads\/2022\/12\/API_template_with_structure.png\")
<\/p>\r\n\r\n\t
Schemas<\/h2>\r\n
![\"esquema](\"https:\/\/document360.com\/wp-content\/uploads\/2022\/12\/spec_wide_schemas.png\")
<\/p>\r\nOpenAPI: puntos fuertes<\/h2>\r\n
\r\n\t
OpenAPI: puntos d\u00e9biles<\/strong><\/h2>\r\n
Menos \u00fatil para el dise\u00f1o y planificaci\u00f3n de la API<\/strong><\/h3>\r\n
No jer\u00e1rquico<\/strong><\/h3>\r\n
\r\n\t
No soporta la herencia del modelo de datos<\/strong><\/h2>\r\n
No es una herramienta \u00abvisual\u00bb<\/strong><\/h3>\r\n
Falta de apoyo para otras arquitecturas<\/strong><\/h3>\r\n
Ejemplo de OpenAPI – Swagger Petstore<\/strong><\/h2>\r\n
![\"Swagger](\"https:\/\/document360.com\/wp-content\/uploads\/2022\/12\/Swagger_UI_examples.png\")
<\/p>\r\nLectura adicional<\/h2>\r\n
![\"Document360\"](\"https:\/\/document360.com\/wp-content\/themes\/document360\/images\/blog-call-to-action.png\")
<\/div>\r\n<\/div>\r\nPreguntas frecuentes<\/h2>\r\n
\r\n\t
\u00bfQu\u00e9 es la OpenAPI? <\/a><\/h3>\r\n
\u00bfCu\u00e1l es la diferencia entre API privada y API abierta? <\/a><\/h3>\r\n
\u00bfQu\u00e9 es OpenAPI y REST API? <\/a><\/h3>\r\n