Então, todos da mesma RAML ou OEA (Swagger)?

No mundo dinâmico dos microsserviços, tudo pode mudar - qualquer componente pode ser reescrito em outro idioma usando diferentes estruturas e arquitetura. Somente os contratos devem permanecer inalterados, para que seja possível interagir com o microsserviço a partir do exterior de maneira permanente, independentemente das metamorfoses internas. E hoje falaremos sobre o nosso problema de escolher um formato para descrever contratos e compartilhar artefatos encontrados.



O post foi preparado por Anna Melekhova e Vladimir Lapatin

Microsserviços. Ao desenvolver o Acronis Cyber ​​Cloud, percebemos que não podíamos fugir deles. E projetar um microsserviço é impossível sem formalizar um contrato, que é a interface de um microsserviço.

Mas quando um produto contém mais de um componente, e o desenvolvimento de um contrato se torna uma atividade regular, você involuntariamente começa a pensar em otimizar o processo. Torna-se óbvio que a interface (contrato) e a implementação (microsserviço) devem corresponder um ao outro, que componentes diferentes devem fazer as mesmas coisas da mesma forma e que, sem uma adoção centralizada de todas essas decisões, cada equipe será forçada a gastar tempo para obtê-las repetidas vezes .


Layout de microsserviço da Amazon do tweet de Werner Vogelis, Amazon CTO
Qual é o dilema? De fato, existem duas maneiras pelas quais os microsserviços interagem - HTTP Rest e gRPC do Google. Não querendo se envolver na pilha de tecnologias do Google, escolhemos o HTTP Rest. As anotações dos contratos HTTP REST são descritas com mais freqüência em um dos dois formatos: RAML e OEA, anteriormente conhecido como Swagger, portanto, cada equipe de desenvolvimento enfrenta a necessidade de escolher um dos padrões. Mas, como se viu, fazer essa escolha pode ser muito difícil.

Por que anotações?

É necessária uma anotação para que um usuário externo possa descobrir facilmente o que pode ser feito com o seu serviço através de sua interface HTTP. Ou seja, em um nível básico, a anotação deve conter pelo menos uma lista de recursos disponíveis, seus métodos HTTP, corpos de solicitação, uma lista de parâmetros, uma indicação dos cabeçalhos necessários e suportados, bem como códigos de retorno e formatos de resposta. Um elemento extremamente importante da anotação do contrato é sua descrição verbal (“o que acontece se você adicionar esse parâmetro de consulta à solicitação?”, “Nesse caso, o código 400 retornará?”)

No entanto, quando se trata de desenvolver um grande número de microsserviços, quero obter benefícios adicionais das anotações escritas. Por exemplo, com base no RAML / Swagger, você pode gerar o código do cliente e do servidor em um grande número de linguagens de programação. Você também pode receber automaticamente a documentação do microsserviço e enviá-la para o portal do desenvolvedor :).


Um exemplo de descrição de contrato estruturado

Menos comum é a prática de testar microsserviços com base em descrições de contrato. Se você escreveu uma anotação e um componente, pode criar um autoteste que verifique a adequação do serviço com vários tipos de dados de entrada. O serviço retorna um código de resposta que não está descrito na anotação? Será capaz de processar corretamente dados incorretamente intencionais?

Além disso, a implementação de alta qualidade não apenas dos contratos em si, mas também das ferramentas para visualizar anotações facilita o trabalho com o microsserviço. Ou seja, se o arquiteto descreveu qualitativamente o contrato, seus projetistas e desenvolvedores implementarão o serviço em outros produtos sem custos adicionais de tempo.

Para a operação de ferramentas adicionais, a RAML e a OEA têm a capacidade de adicionar metadados que não são fornecidos pelo padrão ( por exemplo, isso é feito na OEA ).

Em geral, o campo da criatividade na aplicação de contratos para microsserviços é enorme ... pelo menos teoricamente

Comparação de um ouriço com uma cobra

Atualmente, a área de desenvolvimento prioritário da Acronis é o desenvolvimento da Acronis Cyber ​​Platform. Acronis Cyber ​​Platform - esses são novos pontos de integração de serviços de terceiros com o Acronis Cyber ​​Cloud e parte do agente. Embora nossas APIs internas descritas em RAML estivessem bem conosco, a necessidade de publicar a API novamente levantou a questão da escolha: qual padrão de anotação é melhor usar em nosso trabalho?

Inicialmente, parecia haver duas soluções - esses eram os desenvolvimentos mais comuns do RAML e do Swagger (ou OEA). Mas, de fato, as alternativas são pelo menos não 2, mas 3 ou mais.

Por um lado, existe o RAML - uma linguagem poderosa e eficaz. Ele implementa bem a hierarquia e a herança; portanto, esse formato é mais adequado para grandes empresas que precisam de muitas descrições - ou seja, não um produto, mas muitos microsserviços que possuem partes comuns de contratos - esquemas de autenticação, os mesmos tipos de dados, corpos de erro.

Mas o desenvolvedor de RAML, Mulesoft, ingressou no consórcio Open API que está desenvolvendo o Swagger . Portanto, a RAML suspendeu seu desenvolvimento. Para imaginar o formato do evento, imagine que os mantenedores dos principais componentes do Linux foram trabalhar na Microsoft. Essa situação cria os pré-requisitos para o uso do Swagger, que está se desenvolvendo dinamicamente e, na última terceira versão, praticamente alcança a RAML em termos de flexibilidade e funcionalidade.

Se não fosse por um, mas ...

Como se viu, nem todos os utilitários de código aberto foram atualizados para a versão OAS 3.0. Para microsserviços no Go, o mais crítico será a falta de adaptação do go-swagger à versão mais recente do padrão. No entanto, a diferença entre o Swagger 2 e o Swagger 3 é enorme . Por exemplo, na terceira versão, os desenvolvedores:

• descrição aprimorada dos esquemas de autenticação
• suporte completo para o esquema JSON
• bombeado a capacidade de adicionar exemplos

A situação é engraçada: ao escolher um padrão, você precisa considerar o RAML, o Swagger 2 e o Swagger 3 como alternativas separadas. No entanto, apenas o Swagger 2 tem um bom suporte para o kit de ferramentas OpenSource. A RAML é muito flexível ... e complexa, e o Swagger 3 é pouco suportado pela comunidade; portanto, você precisa usar ferramentas proprietárias ou soluções comerciais, que geralmente são muito caras.

Ao mesmo tempo, se houver muitos recursos interessantes no Swagger, como o portal pronto editor.swagger.io , no qual você pode baixar a anotação e obter sua visualização com uma descrição detalhada, links e links, não há essa possibilidade de uma RAML mais fundamental e menos amigável. Sim, você pode procurar algo entre os projetos no GitHub, encontrar um analógico lá e implantá-lo você mesmo. No entanto, em qualquer caso, alguém precisará oferecer suporte ao portal, o que não é tão conveniente para as necessidades básicas de teste ou uso. Além disso, o swagger é mais "sem princípios", bem ou liberal - ele pode ser gerado a partir de comentários no código, que, obviamente, contraria o princípio da API primeiro e não é suportado por nenhum dos utilitários de RAML,

Ao mesmo tempo, começamos a trabalhar com RAML como uma linguagem mais flexível e, como resultado, tivemos que fazer muito com nossas próprias mãos. Por exemplo, um dos projetos usa o utilitário ramlfications em testes de unidade, que suporta apenas RAML 0.8. Então eu tive que adicionar muletas para que o utilitário pudesse "comer" a versão 1.0 da RAML.

Preciso escolher?

Tendo nos envolvido na adição de um ecossistema de soluções para RAML, chegamos à conclusão de que precisamos converter RAML para Swagger 2 e já executamos toda a automação, verificação, teste e otimização subsequente nele. Essa é uma boa maneira de aproveitar a flexibilidade do RAML e o suporte às ferramentas da comunidade do Swagger.

Para resolver esse problema, existem duas ferramentas OpenSource que devem garantir a conversão de contratos:

1. oas-raml-converter agora é um utilitário não suportado. No processo de trabalhar com ela, descobrimos que ela tem vários problemas com RAMLs complexas que estão "espalhadas" por um grande número de arquivos. Este programa é escrito em JavaScript e executa uma travessia recursiva da árvore de sintaxe. Devido à digitação dinâmica, fica difícil entender esse código, por isso decidimos não perder tempo escrevendo patches para um utilitário que está morrendo.
2. O webapi-parser é uma ferramenta da mesma empresa, que afirma estar pronta para converter tudo e tudo e em qualquer direção. Até o momento, foi anunciado o suporte para RAML 0.8, RAML 1.0 e Swagger 2.0. No entanto, no momento do nosso estudo, o utilitário era EXTREMAMENTE bruto e inutilizável. Os desenvolvedores criam um tipo de RI , que permitirá adicionar rapidamente novos padrões no futuro. Mas, por enquanto, tudo isso simplesmente não funciona.

E estas não são todas as dificuldades que encontramos. Uma das etapas do nosso pipeline é verificar se a RAML do repositório está correta em relação à especificação. Tentamos vários utilitários. Surpreendentemente, todos eles amaldiçoaram nossas anotações em lugares diferentes e com palavrões completamente diferentes. E nem sempre é o caso :).

No final, decidimos pelo projeto agora obsoleto, que também tem vários problemas (às vezes fica fora do azul, tem problemas ao trabalhar com expressões regulares). Assim, não encontramos uma maneira de resolver as tarefas de validação e conversão com base em ferramentas gratuitas e decidimos usar um utilitário comercial. No futuro, quando as ferramentas OpenSource se tornarem mais desenvolvidas, a solução desse problema poderá se tornar mais fácil. Enquanto isso, o tempo e o trabalho envolvidos no “acabamento” nos pareciam mais significativos do que o custo de um serviço comercial.

Conclusão

Depois de tudo isso, queríamos compartilhar nossa experiência e observar que, antes de escolher uma ferramenta para descrever contratos, você precisa determinar claramente o que deseja e qual orçamento está pronto para investir. Se você esquecer o OpenSource, agora há um grande número de serviços e produtos que ajudarão você a verificar, converter, validar. Mas eles são caros e, às vezes, muito caros. Para uma grande empresa, esses custos são toleráveis, mas para uma startup, pode se tornar um grande fardo.

Defina um conjunto de ferramentas que você usará mais tarde. Por exemplo, se você apenas precisar exibir o contrato, será mais fácil usar o Swagger 2, que possui uma API bonita, porque na RAML você precisa levantar e manter o serviço.
Quanto mais tarefas você tiver, maior será a necessidade de ferramentas, e elas serão diferentes para diferentes plataformas, e é melhor se familiarizar imediatamente com as versões disponíveis para fazer uma escolha que minimize seus custos no futuro.

Mas vale a pena reconhecer que todos os ecossistemas que existem hoje são imperfeitos. Portanto, se a empresa possui fãs que gostam de trabalhar em RAML, porque “permite expressar seus pensamentos com mais flexibilidade” ou, pelo contrário, preferem o Swagger, porque “é mais compreensível”, é melhor deixá-los trabalhar naquilo que desejam. Estamos acostumados e desejamos, porque as ferramentas de qualquer um dos formatos precisam ser finalizadas com um arquivo.

Quanto à nossa experiência, nos posts a seguir, falaremos sobre que tipo de verificação estática e dinâmica realizamos com base em nossa arquitetura RAML-Swagger, bem como que documentação geramos a partir de contratos e como tudo funciona.