{"id":38022,"date":"2019-10-31T22:21:14","date_gmt":"2019-10-31T19:21:14","guid":{"rendered":"https:\/\/prohoster.info\/blog\/tak-vse-taki-raml-ili-oas-swagger\/"},"modified":"2019-10-31T22:21:14","modified_gmt":"2019-10-31T19:21:14","slug":"tak-vse-taki-raml-ili-oas-swagger","status":"publish","type":"post","link":"https:\/\/prohoster.info\/es\/blog\/administrirovanie\/tak-vse-taki-raml-ili-oas-swagger","title":{"rendered":"\u00bfRAML o OAS (Swagger)?","gt_translate_keys":[{"key":"rendered","format":"text"}]},"content":{"rendered":"

En el din\u00e1mico mundo de los microservicios, todo puede cambiar: cualquier componente puede reescribirse en otro lenguaje, utilizando diferentes frameworks y arquitecturas. Lo \u00fanico que debe permanecer inalterado son los contratos, de modo que se pueda interactuar con el microservicio de manera constante, independientemente de las metamorfosis internas. Hoy hablaremos sobre nuestro dilema en la elecci\u00f3n del formato de descripci\u00f3n de contratos y compartiremos los artefactos que hemos encontrado. <\/p>\n

\"\u00bfRAML
\n<\/a><\/noindex>
\nPublicaci\u00f3n preparada por Anna Melekhova<\/a><\/noindex> y Vladimir Lapatin<\/a><\/noindex> <\/p>\n

Microservicios.<\/b> Al desarrollar Acronis Cyber Cloud, nos dimos cuenta de que no pod\u00edamos escapar de ellos. El dise\u00f1o de un microservicio es imposible sin la formalizaci\u00f3n de un contrato, que representa la interfaz del microservicio.<\/p>\n

Pero cuando hay m\u00e1s de un componente en el producto y el desarrollo de contratos se convierte en una actividad regular, inevitablemente comienzas a pensar en la optimizaci\u00f3n del proceso. Se hace evidente que la interfaz (contrato) y la implementaci\u00f3n (microservicio) deben coincidir entre s\u00ed, que diferentes componentes deben hacer las mismas cosas de la misma manera, y que sin una toma de decisiones centralizada, cada equipo se ver\u00e1 obligado a gastar tiempo una y otra vez en obtenerlas. <\/p>\n

\"\u00bfRAML
\nEsquema de microservicios de Amazon de un tuit<\/a><\/noindex> de Werner Vogels, CTO de Amazon<\/i>
\n\u00bfCu\u00e1l es, entonces, el dilema? De facto, existen dos formas de interacci\u00f3n entre microservicios: HTTP Rest y gRPC de Google. No queriendo ser parte del stack tecnol\u00f3gico de Google, elegimos HTTP Rest. Las anotaciones de los contratos HTTP REST a menudo se describen en uno de dos formatos: RAML y OAS, anteriormente conocido como Swagger. Por lo tanto, cada equipo de desarrolladores se enfrenta a la necesidad de elegir uno de los est\u00e1ndares. Pero, como se ha descubierto, hacer esta elecci\u00f3n puede ser muy complicado.<\/p>\n

\u00bfPor qu\u00e9 son necesarias las anotaciones?<\/h3>\n

\nLa anotaci\u00f3n es necesaria para que un usuario externo pueda entender f\u00e1cilmente qu\u00e9 se puede hacer con su servicio a trav\u00e9s de su interfaz HTTP. Es decir, a nivel b\u00e1sico, la anotaci\u00f3n debe contener al menos una lista de los recursos disponibles, sus m\u00e9todos HTTP, cuerpos de las solicitudes, enumeraci\u00f3n de par\u00e1metros, indicaci\u00f3n de encabezados necesarios y admitidos, as\u00ed como c\u00f3digos de respuesta y formatos de respuestas. Un elemento extremadamente importante de la anotaci\u00f3n del contrato es su descripci\u00f3n verbal ('\u00bfqu\u00e9 suceder\u00e1 si se agrega este par\u00e1metro de consulta a la solicitud?', '\u00bfen qu\u00e9 caso se devolver\u00e1 el c\u00f3digo 400?')<\/p>\n

Sin embargo, cuando se trata del desarrollo de una gran cantidad de microservicios, se desea obtener un beneficio adicional de las anotaciones escritas. Por ejemplo, de RAML\/Swagger se puede generar tanto c\u00f3digo de cliente como de servidor en una gran cantidad de lenguajes de programaci\u00f3n. Adem\u00e1s, se puede obtener documentaci\u00f3n autom\u00e1ticamente sobre el microservicio y cargarla en su portal de desarrolladores :)<\/p>\n

\"\u00bfRAML
\nEjemplo de descripci\u00f3n estructurada del contrato<\/i><\/p>\n

Es menos com\u00fan la pr\u00e1ctica de probar microservicios bas\u00e1ndose en descripciones de contratos. Si ha escrito tanto la anotaci\u00f3n como el componente, se puede crear una prueba autom\u00e1tica que verifique la adecuaci\u00f3n del funcionamiento del servicio con diversos tipos de datos como entrada. \u00bfEl servicio devuelve alg\u00fan c\u00f3digo de respuesta que no est\u00e9 descrito en la anotaci\u00f3n? \u00bfPodr\u00e1 manejar correctamente datos manifiestamente incorrectos?<\/p>\n

Adem\u00e1s, una implementaci\u00f3n de calidad no solo de los contratos, sino tambi\u00e9n de las herramientas para visualizar las anotaciones facilita el trabajo con el microservicio. Es decir, si el arquitecto describi\u00f3 el contrato de manera adecuada, con base en eso, los dise\u00f1adores y desarrolladores podr\u00e1n implementar el servicio en otros productos sin costos de tiempo adicionales.<\/p>\n

Para trabajar con herramientas adicionales, tanto RAML como OAS tienen la posibilidad de agregar metadatos no previstos por el est\u00e1ndar (por ejemplo, as\u00ed es como se hace en OAS<\/a><\/noindex>).<\/p>\n

En general, el campo para la creatividad en la aplicaci\u00f3n de contratos para microservicios es enorme... al menos te\u00f3ricamente<\/p>\n

Comparaci\u00f3n entre un erizo y una culebra<\/h3>\n

\nActualmente, la direcci\u00f3n prioritaria de desarrollo en Acronis es el desarrollo de Acronis Cyber Platform. Acronis Cyber Platform son nuevos puntos de integraci\u00f3n de servicios externos con Acronis Cyber Cloud y la parte de agente. Aunque nuestras API internas, descritas en RAML, nos satisfac\u00edan, la necesidad de publicar la API volvi\u00f3 a plantear la cuesti\u00f3n de elecci\u00f3n: \u00bfqu\u00e9 est\u00e1ndar de anotaciones es mejor utilizar para nuestro trabajo?<\/p>\n

Inicialmente parec\u00eda que hab\u00eda dos soluciones: las implementaciones m\u00e1s comunes de RAML y Swagger (o OAS). Pero en realidad result\u00f3 que hay al menos 3 o m\u00e1s alternativas.<\/p>\n

Por un lado est\u00e1 RAML, un lenguaje poderoso y efectivo. Tiene bien desarrollada la jerarqu\u00eda y herencia, por lo que este formato es m\u00e1s adecuado para grandes empresas que necesitan muchas descripciones, es decir, no un solo producto, sino muchos microservicios que tienen partes comunes de contratos: esquemas de autenticaci\u00f3n, tipos de datos similares, cuerpos de errores.<\/p>\n

Sin embargo, el desarrollador de RAML, la empresa Mulesoft, se uni\u00f3 al consorcio Open API, que se ocupa del desarrollo Swagger<\/a><\/noindex>. Por lo tanto, el desarrollo de RAML se detuvo. Para imaginar el formato del evento, imagina que los mantenedores de los componentes principales de Linux se fueron a trabajar a Microsoft. Tal situaci\u00f3n crea las condiciones para utilizar Swagger, que se est\u00e1 desarrollando din\u00e1micamente y en la \u00faltima \u2014 tercera versi\u00f3n \u2014 pr\u00e1cticamente alcanza a RAML en flexibilidad y funcionalidad.<\/p>\n

Si no fuera por un pero...<\/h3>\n

\nResulta que no todas las utilidades de c\u00f3digo abierto se actualizaron a la versi\u00f3n OAS 3.0. Para los microservicios en Go, la falta de adaptaci\u00f3n de go-swagger<\/a><\/noindex> a la nueva versi\u00f3n del est\u00e1ndar ser\u00e1 lo m\u00e1s cr\u00edtico. Sin embargo, la diferencia entre Swagger 2 y Swagger 3 es enorme<\/a><\/noindex>. Por ejemplo, en la tercera versi\u00f3n, los desarrolladores:<\/p>\n