Alors, c'est RAML ou OAS (Swagger) ?

Dans le monde dynamique des microservices, tout peut changer — n'importe quel composant peut être réécrit dans un autre langage, en utilisant d'autres frameworks et architectures. Ce qui doit rester inchangé, ce sont les contrats, afin de pouvoir interagir avec le microservice de façon constante, indépendamment des métamorphoses internes. Aujourd'hui, nous allons parler de notre problème de choix de format de description des contrats et partager les artefacts que nous avons trouvés.

Post préparé par Anna Melekhova et Vladimir Lapatin

Microservices. Dans le développement d'Acronis Cyber Cloud, nous avons compris que nous ne pouvions pas y échapper. La conception d'un microservice est impossible sans formalisation d'un contrat, qui représente l'interface du microservice.

Mais lorsque le produit contient plus d'un composant, et que le développement du contrat devient une activité régulière, on commence inévitablement à réfléchir à l'optimisation du processus. Il devient évident que l'interface (contrat) et l'implémentation (microservice) doivent correspondre l'une à l'autre, que les différents composants doivent faire les mêmes choses de la même manière, et que sans une adoption centralisée de toutes ces décisions, chaque équipe sera forcée de passer de nouveau du temps à les obtenir.

Schéma des microservices d'Amazon issu de un tweet de Werner Vogels, CTO d'Amazon
Quelle est donc la dilemme ? De facto, il existe deux manières d'interagir entre les microservices – HTTP Rest et gRPC de Google. Ne souhaitant pas être impliqués dans la pile technologique de Google, nous avons choisi HTTP Rest. Les annotations aux contrats HTTP REST sont généralement décrites dans l'un des deux formats : RAML et OAS, anciennement connu sous le nom de Swagger. Par conséquent, chaque équipe de développement est confrontée à la nécessité de faire un choix en faveur de l'un des standards. Mais, comme il s'est avéré, faire ce choix peut être très difficile.

Pourquoi avons-nous besoin d'annotations ?

Une annotation est nécessaire pour que l'utilisateur externe puisse facilement comprendre ce qu'il peut faire avec votre service via son interface HTTP. À un niveau de base, l'annotation doit contenir au minimum une liste des ressources disponibles, leurs méthodes HTTP, les corps des requêtes, l'énumération des paramètres, l'indication des en-têtes requis et pris en charge, ainsi que des codes de retour et des formats de réponses. Un élément crucial de l'annotation du contrat est également leur description verbale (« que se passera-t-il si ce paramètre de requête est ajouté à la requête ? », « dans quelle situation le code 400 sera-t-il retourné ? »)

Cependant, lorsqu'il s'agit de développer un grand nombre de microservices, on souhaite tirer un bénéfice supplémentaire des annotations écrites. Par exemple, à partir de RAML/Swagger, il est possible de générer à 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 :)

Exemple de description structurée d'un contrat

Il est moins fréquent de voir la pratique de tester des microservices sur la base des descriptions de contrats. Si vous avez rédigé à la fois l'annotation et le composant, vous pouvez créer un autotest qui vérifie l'adéquation du service avec divers types de données en entrée. Le service retourne-t-il un code de réponse non décrit dans l'annotation ? Peut-il traiter correctement des données manifestement incorrectes ?

De plus, une mise en œuvre de qualité des contrats eux-mêmes, ainsi que des outils de visualisation des annotations, permet de simplifier le travail avec le microservice. Autrement dit, si l'architecte a décrit le contrat de manière adéquate, sur cette base, les designers et les développeurs pourront intégrer le service dans d'autres produits sans coûts de temps supplémentaires.

Pour le fonctionnement d'outils supplémentaires, RAML et OAS ont la possibilité d'ajouter des métadonnées non prévues par la norme (par exemple, c'est ainsi que cela se fait dans OAS).

En général, le champ pour la créativité dans l'application des contrats pour les microservices est immense… du moins théoriquement

Comparaison d'un hérisson avec une couleuvre

Actuellement, la priorité de développement chez Acronis est l'évolution de la plateforme Acronis Cyber. Acronis Cyber Platform est un nouvel ensemble de points d'intégration pour les services tiers avec Acronis Cyber Cloud et la partie agent. Bien que nos API internes, décrites dans RAML, nous satisfaisaient, la nécessité de publier une API a de nouveau relancé la question : quelle norme d'annotations devrions-nous utiliser pour notre travail ?

Au départ, il semblait qu'il y avait deux solutions — les développements les plus répandus, RAML et Swagger (ou OAS). Mais en fait, il s'est avéré qu'il y a au minimum trois alternatives ou plus.

D'une part, il y a RAML – un langage puissant et efficace. Il réalise bien la hiérarchie et l'héritage, ce qui fait que ce format est plus adapté aux grandes entreprises ayant besoin de nombreuses descriptions — c'est-à-dire pas d'un seul produit, mais de nombreux microservices ayant des parties communes dans leurs contrats — schémas d'authentification, types de données identiques, corps d'erreur.

Mais le développeur de RAML, la société Mulesoft, a rejoint le consortium Open API, qui s'occupe du développement Swagger. Par conséquent, RAML a suspendu son développement. Pour imaginer le format événement, imaginez que les mainteneurs des composants principaux de Linux vont travailler chez Microsoft. Une telle situation crée les conditions nécessaires pour adopter Swagger, qui évolue dynamiquement et qui, dans sa dernière — troisième version — rattrape pratiquement RAML en flexibilité et en fonctionnalité.

S'il n'y avait pas un mais…

Il s'est avéré que toutes les utilitaires open-source ne se sont pas mises à jour vers la version OAS 3.0. Pour les microservices en Go, le manque d'adaptation go-swagger à la dernière version de la norme s'avère critique. Cependant, la différence entre Swagger 2 et Swagger 3 — est énorme. Par exemple, dans la troisième version, les développeurs :

• ont amélioré la description des schémas d'authentification
• ont finalisé le support du JSON Schema
• ont renforcé la possibilité d'ajouter des exemples

La situation devient amusante : lors du choix d'une norme, il est nécessaire de considérer RAML, Swagger 2 et Swagger 3 comme des alternatives distinctes. Dans ce cas, seul Swagger 2 bénéficie d'un bon soutien des outils Open Source. RAML est très flexible… et complexe, tandis que Swagger 3 est faiblement soutenu par la communauté, vous devrez donc utiliser des outils de développement interne ou des solutions commerciales qui, en général, coûtent très cher.

Il convient de noter que si Swagger propose de nombreuses fonctionnalités intéressantes, telles qu'un portail prêt à l'emploi editor.swagger.io, où vous pouvez télécharger une annotation et obtenir sa visualisation avec une description détaillée, des liens et des relations, alors que pour le RAML plus fondamental et moins convivial, cette possibilité n'existe pas. Oui, il est possible de rechercher quelque chose parmi les projets sur GitHub, d'y trouver un équivalent et de le déployer vous-même. Cependant, dans tous les cas, quelqu'un devra maintenir le portail, ce qui n'est pas si pratique pour un usage de base ou des besoins de test. De plus, Swagger est plus « libre » ou « libéral » — il peut être généré à partir de commentaires dans le code, ce qui, bien sûr, va à l'encontre du principe de l'API first et n'est supporté par aucun des outils RAML.

Nous avons commencé à travailler avec RAML à l'époque, étant un langage plus flexible, et finalement, nous avons dû faire beaucoup de choses nous-mêmes. Par exemple, dans l'un des projets, nous utilisons un outil ramlfications dans les tests unitaires, qui ne supporte que RAML 0.8. Il a donc fallu ajouter des rustines pour que l'outil puisse « digérer » les versions RAML 1.0.

Et faut-il choisir ?

Après avoir galéré à ajouter des solutions à l'écosystème autour de RAML, nous sommes arrivés à la conclusion qu'il était nécessaire de convertir RAML en Swagger 2 et de faire toute l'automatisation, la vérification, le test et l'optimisation dans ce dernier. C'est un bon moyen d'utiliser à la fois la flexibilité de RAML et le soutien des outils de la communauté Swagger.

Pour résoudre ce problème, il existe deux outils OpenSource qui devraient permettre la conversion des contrats :

1. oas-raml-converter – un outil actuellement non supporté. Au cours de notre travail avec, nous avons découvert qu'il avait un certain nombre de problèmes avec des RAML complexes, qui sont « étalés » sur un grand nombre de fichiers. Ce programme est écrit en JavaScript et effectue un parcours récursif de l'arbre syntaxique. En raison de la typage dynamique, il devient difficile de comprendre ce code, donc nous avons décidé de ne pas perdre de temps à écrire des patchs pour un outil moribond.
2. webapi-parser — un outil de la même entreprise, qui prétend être capable de convertir tout et n'importe quoi, et ce dans les deux sens. À ce jour, il supporte RAML 0.8, RAML 1.0 et Swagger 2.0. Cependant, au moment de notre recherche, l'outil était encore EXTRÊMEMENT brut et inutilisable. Les développeurs créent une sorte de IR, ce qui leur permettra d'ajouter rapidement de nouvelles normes à l'avenir. Mais pour l'instant, tout cela ne fonctionne tout simplement pas.

Et ce n'est pas tout, les difficultés auxquelles nous avons été confrontés. L'une des étapes de notre pipeline consiste à vérifier que le RAML du dépôt est correct par rapport à la spécification. Nous avons essayé plusieurs outils. Étonnamment, tous ont critiqué nos annotations à différents endroits avec des mots totalement déplacés. Et ce n'était pas toujours justifié :).

Finalement, nous nous sommes arrêtés sur un projet désormais obsolète, qui présente également un certain nombre de problèmes (il plante parfois sans raison, a des problèmes avec les expressions régulières). Ainsi, nous n'avons pas trouvé de moyen de résoudre les tâches de validation et de conversion à l'aide d'outils gratuits, et avons décidé d'utiliser un outil commercial. À l'avenir, lorsque les outils OpenSource seront plus avancés, résoudre cette tâche pourrait devenir plus facile. Mais pour l'instant, le coût en temps et en efforts pour le 'peaufiner' nous a semblé plus important que le prix du service commercial.

Conclusion

Après tout cela, nous avons ressenti le besoin de partager notre expérience et de souligner qu'avant de choisir un outil pour décrire les contrats, il est essentiel de définir clairement ce que vous en attendez et quel budget vous êtes prêt à investir. Si l'on ignore l'OpenSource, il existe déjà de nombreux services et produits qui peuvent aider à vérifier, convertir, valider. Mais ils sont chers, parfois très chers. Pour une grande entreprise, de telles dépenses sont acceptables, mais pour une startup, cela peut représenter un fardeau important.

Déterminez l'ensemble des outils que vous allez utiliser par la suite. Par exemple, si vous avez simplement besoin d'afficher un contrat, il sera plus facile d'utiliser Swagger 2, qui dispose d'une API élégante, alors qu'avec le RAML, vous devrez mettre en place et maintenir le service vous-même.
Plus vous aurez de tâches, plus vos besoins en outils s'élargiront, et ils varient selon les plateformes. Il est donc préférable de se familiariser dès le départ avec les versions disponibles pour faire un choix qui minimisera vos coûts à l'avenir.

Il convient de reconnaître que tous les écosystèmes existants aujourd'hui ne sont pas parfaits. Donc, s'il y a des fans dans l'entreprise qui aiment travailler avec RAML parce qu'il "permet d'exprimer les idées de manière plus flexible", ou au contraire, préfèrent Swagger parce qu'il "est plus compréhensible", il est préférable de les laisser travailler avec ce qu'ils connaissent et préfèrent, car les outils de chaque format nécessitent des ajustements.

En ce qui concerne notre expérience, dans les prochains posts, nous parlerons des vérifications — statiques et dynamiques — que nous effectuons sur notre architecture RAML-Swagger, ainsi que de la documentation que nous générons à partir des contrats et de la manière dont tout cela fonctionne.

Seuls les utilisateurs enregistrés peuvent participer au sondage. Connectez-vous, s'il vous plaît.

Quel langage utilisez-vous pour annoter les contrats des microservices ?

• RAML 0.8

• RAML 1.0

• Swagger 2

• OAS3 (aussi connu sous le nom de )

• Blueprint

• Autre

• Je n'utilise pas

100 utilisateurs ont voté. 24 utilisateurs se sont abstenus.

Source : habr.com