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

Dans le monde dynamique des microservices, tout peut changer \u2014 n'importe quel composant peut \u00eatre r\u00e9\u00e9crit dans un autre langage, en utilisant d'autres frameworks et architectures. Ce qui doit rester inchang\u00e9, ce sont les contrats, afin de pouvoir interagir avec le microservice de fa\u00e7on constante, ind\u00e9pendamment des m\u00e9tamorphoses internes. Aujourd'hui, nous allons parler de notre probl\u00e8me de choix de format de description des contrats et partager les artefacts que nous avons trouv\u00e9s. <\/p>\n

\"Alors,
\n<\/a><\/noindex>
\nPost pr\u00e9par\u00e9 par Anna Melekhova<\/a><\/noindex> et Vladimir Lapatin<\/a><\/noindex> <\/p>\n

Microservices.<\/b> Dans le d\u00e9veloppement d'Acronis Cyber Cloud, nous avons compris que nous ne pouvions pas y \u00e9chapper. La conception d'un microservice est impossible sans formalisation d'un contrat, qui repr\u00e9sente l'interface du microservice.<\/p>\n

Mais lorsque le produit contient plus d'un composant, et que le d\u00e9veloppement du contrat devient une activit\u00e9 r\u00e9guli\u00e8re, on commence in\u00e9vitablement \u00e0 r\u00e9fl\u00e9chir \u00e0 l'optimisation du processus. Il devient \u00e9vident que l'interface (contrat) et l'impl\u00e9mentation (microservice) doivent correspondre l'une \u00e0 l'autre, que les diff\u00e9rents composants doivent faire les m\u00eames choses de la m\u00eame mani\u00e8re, et que sans une adoption centralis\u00e9e de toutes ces d\u00e9cisions, chaque \u00e9quipe sera forc\u00e9e de passer de nouveau du temps \u00e0 les obtenir. <\/p>\n

\"Alors,
\nSch\u00e9ma des microservices d'Amazon issu de un tweet<\/a><\/noindex> de Werner Vogels, CTO d'Amazon<\/i>
\nQuelle est donc la dilemme ? De facto, il existe deux mani\u00e8res d'interagir entre les microservices \u2013 HTTP Rest et gRPC de Google. Ne souhaitant pas \u00eatre impliqu\u00e9s dans la pile technologique de Google, nous avons choisi HTTP Rest. Les annotations aux contrats HTTP REST sont g\u00e9n\u00e9ralement d\u00e9crites dans l'un des deux formats : RAML et OAS, anciennement connu sous le nom de Swagger. Par cons\u00e9quent, chaque \u00e9quipe de d\u00e9veloppement est confront\u00e9e \u00e0 la n\u00e9cessit\u00e9 de faire un choix en faveur de l'un des standards. Mais, comme il s'est av\u00e9r\u00e9, faire ce choix peut \u00eatre tr\u00e8s difficile.<\/p>\n

Pourquoi avons-nous besoin d'annotations ?<\/h3>\n

\nUne annotation est n\u00e9cessaire pour que l'utilisateur externe puisse facilement comprendre ce qu'il peut faire avec votre service via son interface HTTP. \u00c0 un niveau de base, l'annotation doit contenir au minimum une liste des ressources disponibles, leurs m\u00e9thodes HTTP, les corps des requ\u00eates, l'\u00e9num\u00e9ration des param\u00e8tres, l'indication des en-t\u00eates requis et pris en charge, ainsi que des codes de retour et des formats de r\u00e9ponses. Un \u00e9l\u00e9ment crucial de l'annotation du contrat est \u00e9galement leur description verbale (\u00ab que se passera-t-il si ce param\u00e8tre de requ\u00eate est ajout\u00e9 \u00e0 la requ\u00eate ? \u00bb, \u00ab dans quelle situation le code 400 sera-t-il retourn\u00e9 ? \u00bb)<\/p>\n

Cependant, lorsqu'il s'agit de d\u00e9velopper un grand nombre de microservices, on souhaite tirer un b\u00e9n\u00e9fice suppl\u00e9mentaire des annotations \u00e9crites. Par exemple, \u00e0 partir de RAML\/Swagger, il est possible de g\u00e9n\u00e9rer \u00e0 la fois du code client et serveur dans un grand nombre de langages de programmation. De plus, il est possible d'obtenir automatiquement la documentation du microservice et de la publier sur votre developer-portal :)<\/p>\n

\"Alors,
\nExemple de description structur\u00e9e d'un contrat<\/i><\/p>\n

Il est moins fr\u00e9quent de voir la pratique de tester des microservices sur la base des descriptions de contrats. Si vous avez r\u00e9dig\u00e9 \u00e0 la fois l'annotation et le composant, vous pouvez cr\u00e9er un autotest qui v\u00e9rifie l'ad\u00e9quation du service avec divers types de donn\u00e9es en entr\u00e9e. Le service retourne-t-il un code de r\u00e9ponse non d\u00e9crit dans l'annotation ? Peut-il traiter correctement des donn\u00e9es manifestement incorrectes ?<\/p>\n

De plus, une mise en \u0153uvre de qualit\u00e9 des contrats eux-m\u00eames, ainsi que des outils de visualisation des annotations, permet de simplifier le travail avec le microservice. Autrement dit, si l'architecte a d\u00e9crit le contrat de mani\u00e8re ad\u00e9quate, sur cette base, les designers et les d\u00e9veloppeurs pourront int\u00e9grer le service dans d'autres produits sans co\u00fbts de temps suppl\u00e9mentaires.<\/p>\n

Pour le fonctionnement d'outils suppl\u00e9mentaires, RAML et OAS ont la possibilit\u00e9 d'ajouter des m\u00e9tadonn\u00e9es non pr\u00e9vues par la norme (par exemple, c'est ainsi que cela se fait dans OAS<\/a><\/noindex>).<\/p>\n

En g\u00e9n\u00e9ral, le champ pour la cr\u00e9ativit\u00e9 dans l'application des contrats pour les microservices est immense\u2026 du moins th\u00e9oriquement<\/p>\n

Comparaison d'un h\u00e9risson avec une couleuvre<\/h3>\n

\nActuellement, la priorit\u00e9 de d\u00e9veloppement chez Acronis est l'\u00e9volution de la plateforme Acronis Cyber. Acronis Cyber Platform est un nouvel ensemble de points d'int\u00e9gration pour les services tiers avec Acronis Cyber Cloud et la partie agent. Bien que nos API internes, d\u00e9crites dans RAML, nous satisfaisaient, la n\u00e9cessit\u00e9 de publier une API a de nouveau relanc\u00e9 la question : quelle norme d'annotations devrions-nous utiliser pour notre travail ?<\/p>\n

Au d\u00e9part, il semblait qu'il y avait deux solutions \u2014 les d\u00e9veloppements les plus r\u00e9pandus, RAML et Swagger (ou OAS). Mais en fait, il s'est av\u00e9r\u00e9 qu'il y a au minimum trois alternatives ou plus.<\/p>\n

D'une part, il y a RAML \u2013 un langage puissant et efficace. Il r\u00e9alise bien la hi\u00e9rarchie et l'h\u00e9ritage, ce qui fait que ce format est plus adapt\u00e9 aux grandes entreprises ayant besoin de nombreuses descriptions \u2014 c'est-\u00e0-dire pas d'un seul produit, mais de nombreux microservices ayant des parties communes dans leurs contrats \u2014 sch\u00e9mas d'authentification, types de donn\u00e9es identiques, corps d'erreur.<\/p>\n

Mais le d\u00e9veloppeur de RAML, la soci\u00e9t\u00e9 Mulesoft, a rejoint le consortium Open API, qui s'occupe du d\u00e9veloppement Swagger<\/a><\/noindex>. Par cons\u00e9quent, RAML a suspendu son d\u00e9veloppement. Pour imaginer le format \u00e9v\u00e9nement, imaginez que les mainteneurs des composants principaux de Linux vont travailler chez Microsoft. Une telle situation cr\u00e9e les conditions n\u00e9cessaires pour adopter Swagger, qui \u00e9volue dynamiquement et qui, dans sa derni\u00e8re \u2014 troisi\u00e8me version \u2014 rattrape pratiquement RAML en flexibilit\u00e9 et en fonctionnalit\u00e9.<\/p>\n

S'il n'y avait pas un mais\u2026<\/h3>\n

\nIl s'est av\u00e9r\u00e9 que toutes les utilitaires open-source ne se sont pas mises \u00e0 jour vers la version OAS 3.0. Pour les microservices en Go, le manque d'adaptation go-swagger<\/a><\/noindex> \u00e0 la derni\u00e8re version de la norme s'av\u00e8re critique. Cependant, la diff\u00e9rence entre Swagger 2 et Swagger 3 \u2014 est \u00e9norme<\/a><\/noindex>. Par exemple, dans la troisi\u00e8me version, les d\u00e9veloppeurs :<\/p>\n