{"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\/pt\/blog\/administrirovanie\/tak-vse-taki-raml-ili-oas-swagger","title":{"rendered":"Ent\u00e3o, RAML ou OAS (Swagger)?","gt_translate_keys":[{"key":"rendered","format":"text"}]},"content":{"rendered":"

Em um mundo din\u00e2mico de microsservi\u00e7os, tudo pode mudar \u2014 qualquer componente pode ser reescrito em outra linguagem, utilizando diferentes frameworks e arquiteturas. Apenas os contratos devem permanecer imut\u00e1veis, para que a intera\u00e7\u00e3o com o microsservi\u00e7o possa ocorrer de forma consistente do exterior, independentemente das metamorfoses internas. Hoje, iremos falar sobre nosso dilema na escolha do formato de descri\u00e7\u00e3o dos contratos e compartilhar os artefatos encontrados. <\/p>\n

\"Ent\u00e3o,
\n<\/a><\/noindex>
\nPost elaborado por Anna Melekhova<\/a><\/noindex> e Vladimir Lapatin<\/a><\/noindex> <\/p>\n

Microsservi\u00e7os.<\/b> Durante o desenvolvimento do Acronis Cyber Cloud, percebemos que n\u00e3o poder\u00edamos evitar isso. E o design de um microsservi\u00e7o \u00e9 imposs\u00edvel sem a formaliza\u00e7\u00e3o do contrato, que representa a interface do microsservi\u00e7o.<\/p>\n

Mas quando um produto cont\u00e9m mais de um componente, e o desenvolvimento do contrato se torna uma atividade regular, voc\u00ea come\u00e7a a pensar na otimiza\u00e7\u00e3o do processo. Torna-se evidente que a interface (contrato) e a implementa\u00e7\u00e3o (microsservi\u00e7o) devem corresponder uma \u00e0 outra, que diferentes componentes devem realizar as mesmas fun\u00e7\u00f5es de maneira uniforme, e que sem uma entrega centralizada de todas essas decis\u00f5es, cada equipe precisar\u00e1, repetidamente, reinvestir tempo para obt\u00ea-las. <\/p>\n

\"Ent\u00e3o,
\nEsquema de microsservi\u00e7os da Amazon de um tweet<\/a><\/noindex> de Werner Vogels, CTO da Amazon<\/i>
\nQual \u00e9, ent\u00e3o, o dilema? De fato, existem duas maneiras de os microsservi\u00e7os interagirem - HTTP Rest e gRPC da Google. N\u00e3o desejando ser envolvido na stack de tecnologias da Google, escolhemos HTTP Rest. Anota\u00e7\u00f5es de contratos HTTP REST geralmente s\u00e3o descritas em um dos dois formatos: RAML e OAS, anteriormente conhecido como Swagger. Portanto, cada equipe de desenvolvimento enfrenta a necessidade de escolher um dos padr\u00f5es. Mas, como se revelou, fazer essa escolha pode ser bastante desafiador.<\/p>\n

Por que s\u00e3o necess\u00e1rias anota\u00e7\u00f5es?<\/h3>\n

\nA anota\u00e7\u00e3o \u00e9 necess\u00e1ria para que um usu\u00e1rio externo consiga entender facilmente o que pode ser feito com seu servi\u00e7o atrav\u00e9s da interface HTTP. Ou seja, em um n\u00edvel b\u00e1sico, a anota\u00e7\u00e3o deve conter pelo menos uma lista de recursos dispon\u00edveis, seus m\u00e9todos HTTP, corpos de solicita\u00e7\u00f5es, enumera\u00e7\u00e3o de par\u00e2metros, indica\u00e7\u00e3o de cabe\u00e7alhos necess\u00e1rios e suportados, bem como c\u00f3digos de retorno e formatos de resposta. Um elemento extremamente importante da anota\u00e7\u00e3o do contrato \u00e9 a descri\u00e7\u00e3o verbal deles (\u201co que acontecer\u00e1 se esse query-par\u00e2metro for adicionado \u00e0 solicita\u00e7\u00e3o?\u201d, \u201cem qual caso retornar\u00e1 o c\u00f3digo 400?\u201d)<\/p>\n

No entanto, quando se trata de desenvolver um grande n\u00famero de microsservi\u00e7os, \u00e9 desej\u00e1vel extrair mais benef\u00edcios das anota\u00e7\u00f5es escritas. Por exemplo, com base no RAML\/Swagger, \u00e9 poss\u00edvel gerar tanto c\u00f3digo cliente quanto servidor em uma enorme variedade de linguagens de programa\u00e7\u00e3o. Al\u00e9m disso, \u00e9 poss\u00edvel obter automaticamente a documenta\u00e7\u00e3o do microsservi\u00e7o e public\u00e1-la em seu portal de desenvolvedores :).<\/p>\n

\"Ent\u00e3o,
\nExemplo de descri\u00e7\u00e3o estruturada de contrato<\/i><\/p>\n

\u00c9 menos comum a pr\u00e1tica de testar microsservi\u00e7os com base nas descri\u00e7\u00f5es dos contratos. Se voc\u00ea escreveu tanto a anota\u00e7\u00e3o quanto o componente, pode criar um autoteste que verifique a adequa\u00e7\u00e3o do funcionamento do servi\u00e7o com diferentes tipos de dados de entrada. O servi\u00e7o retorna algum c\u00f3digo de resposta que n\u00e3o est\u00e1 descrito na anota\u00e7\u00e3o? Ele consegue processar corretamente dados deliberadamente inv\u00e1lidos?<\/p>\n

Al\u00e9m disso, uma implementa\u00e7\u00e3o de qualidade n\u00e3o apenas dos pr\u00f3prios contratos, mas tamb\u00e9m de ferramentas para visualiza\u00e7\u00e3o de anota\u00e7\u00f5es pode simplificar o trabalho com o microsservi\u00e7o. Ou seja, se o arquiteto descreveu o contrato com qualidade, com base nele, os designers e desenvolvedores poder\u00e3o integrar o servi\u00e7o em outros produtos sem custos de tempo adicionais.<\/p>\n

Para o funcionamento de ferramentas adicionais, tanto o RAML quanto o OAS t\u00eam a capacidade de adicionar metadados n\u00e3o previstos pelo padr\u00e3o (por exemplo, assim \u00e9 feito no OAS<\/a><\/noindex>).<\/p>\n

Em geral, h\u00e1 um grande espa\u00e7o para criatividade na aplica\u00e7\u00e3o de contratos para microsservi\u00e7os\u2026 pelo menos teoricamente<\/p>\n

Compara\u00e7\u00e3o de um ouri\u00e7o com uma cobra<\/h3>\n

\nAtualmente, a principal linha de desenvolvimento na Acronis \u00e9 a evolu\u00e7\u00e3o da Acronis Cyber Platform. A Acronis Cyber Platform \u00e9 uma nova interface de integra\u00e7\u00e3o de servi\u00e7os de terceiros com a Acronis Cyber Cloud e com a parte de ag\u00eancia. Embora nossas APIs internas, descritas em RAML, estivessem funcionando bem para n\u00f3s, a necessidade de publicar a API levantou novamente a quest\u00e3o da escolha: qual padr\u00e3o de anota\u00e7\u00f5es \u00e9 melhor para o nosso trabalho?<\/p>\n

Inicialmente, parecia que havia duas solu\u00e7\u00f5es \u2014 as mais comuns, RAML e Swagger (ou OAS). Mas, na pr\u00e1tica, n\u00e3o se tratava de apenas duas alternativas, mas sim de tr\u00eas ou mais.<\/p>\n

De um lado, temos o RAML \u2014 uma linguagem poderosa e eficiente. Ele implementa bem hierarquias e heran\u00e7as, tornando esse formato mais adequado para grandes empresas que precisam de muitas descri\u00e7\u00f5es \u2014 ou seja, n\u00e3o um produto, mas muitos microservi\u00e7os que possuem partes comuns nos contratos \u2014 esquemas de autentica\u00e7\u00e3o, tipos de dados id\u00eanticos, corpos de erro.<\/p>\n

Mas o desenvolvedor do RAML, a empresa Mulesoft, se juntou ao cons\u00f3rcio Open API, que est\u00e1 focado no desenvolvimento do Swagger<\/a><\/noindex>. Portanto, o desenvolvimento do RAML foi suspenso. Para imaginar a situa\u00e7\u00e3o do formato, considere que os mantenedores dos componentes principais do Linux foram trabalhar na Microsoft. Essa situa\u00e7\u00e3o gera condi\u00e7\u00f5es para o uso do Swagger, que est\u00e1 em desenvolvimento din\u00e2mico e, na sua \u00faltima \u2014 terceira vers\u00e3o \u2014 est\u00e1 praticamente alcan\u00e7ando o RAML em flexibilidade e funcionalidade.<\/p>\n

Se n\u00e3o fosse por um pequeno detalhe...<\/h3>\n

\nComo se viu, nem todas as utilidades de c\u00f3digo aberto foram atualizadas para a vers\u00e3o OAS 3.0. Para microservi\u00e7os em Go, a falta de adapta\u00e7\u00e3o do go-swagger<\/a><\/noindex> para a nova vers\u00e3o do padr\u00e3o ser\u00e1 extremamente cr\u00edtica. No entanto, a diferen\u00e7a entre o Swagger 2 e o Swagger 3 \u00e9 enorme.<\/a><\/noindex>Por exemplo, na terceira vers\u00e3o, os desenvolvedores:<\/p>\n