在微服务的动态世界中，任何事情都可以改变-任何组件都可以使用不同的框架和体系结构以另一种语言重写。 只有合同应该保持不变，以便有可能在某种永久性的基础上与外部微服务进行交互，而与内部变形无关。 今天，我们将讨论选择格式来描述合同并共享发现的工件的问题。
该帖子由
Anna Melekhova和
Vladimir Lapatin准备微服务。 在开发Acronis网络云时，我们意识到我们无法摆脱它们。 没有正式的合同即微服务的接口，就不可能设计微服务。
但是，当产品包含多个组件并且合同的制定成为常规活动时，您会不由自主地开始考虑优化流程。 显而易见，接口（合同）和实现（微服务）应该相互对应，不同的组件应该做相同的事情，并且如果没有集中采用所有这些决定，每个团队将不得不花时间一次又一次地获取它们。 。
Amazon CTO Werner Vogelis 推文中的 Amazon微服务布局困境是什么？ 实际上，微服务有两种交互方式-HTTP Rest和Google的gRPC。 不想参与Google技术堆栈，我们选择了HTTP Rest。 HTTP REST合同的注释通常以以下两种格式之一进行描述：RAML和OAS（以前称为Swagger），因此，每个开发团队都需要选择一种标准。 但是，事实证明，做出此选择可能非常困难。
为什么要注释？
需要批注，以便外部用户可以通过其HTTP界面轻松确定可以对您的服务执行的操作。 也就是说，在基本级别上，注释应至少包含可用资源，其HTTP方法，请求主体，参数枚举，必要和支持的标头的指示以及返回码和响应格式的列表。 合同注释的一个非常重要的元素是它们的口头描述（“如果将此查询参数添加到请求中会发生什么？”，“在这种情况下将返回400代码？”）
不过，在开发大量微服务时，我想从书面注释中获得更多好处。 例如，基于RAML / Swagger，您可以使用大量的编程语言生成客户端和服务器代码。 您还可以自动接收有关微服务的文档，并将其上传到您的开发人员门户:)。
结构化合同描述的示例基于合同描述测试微服务的实践较少见。 如果编写了批注和组件，则可以创建自动测试，以使用各种类型的输入数据来检查服务的适当性。 服务是否返回注释中未描述的响应代码？ 它是否能够正确处理已知不正确的数据？
此外，不仅合同本身的高质量实现，而且注释的可视化工具的高质量实现，都使得使用微服务更容易。 也就是说，如果架构师对合同进行了定性描述，则设计人员和开发人员将在此基础上以其他产品实施该服务，而无需花费额外的时间。
对于其他工具的操作，RAML和OAS都能够添加标准未提供的元数据（
例如，这是在OAS中完成的 ）。
通常，在微服务合同的应用中，创造力的领域很大……至少在理论上
刺猬与蛇的比较
当前，Acronis的优先开发领域是Acronis网络平台的开发。 Acronis网络平台-这些是第三方服务与Acronis网络云和代理部分集成的新点。 尽管我们在RAML中描述的内部API对我们来说还不错，但是再次发布API的需求又引起了选择的问题：哪种注释标准更适合我们的工作？
最初，似乎有两种解决方案-这是RAML和Swagger（或OAS）最常见的发展。 但实际上，事实证明，替代方案至少不是2，而是3或更多。
一方面，RAML是一种强大而有效的语言。 它很好地实现了层次结构和继承，因此这种格式更适合需要很多描述的大型公司-即不是一种产品，而是许多具有契约共同部分的微服务-认证方案，相同的数据类型，错误体。
但是RAML开发人员Mulesoft加入了正在开发
Swagger的Open API联盟。 因此，RAML暂停了其开发。 想像一下事件的格式，想像一下主要Linux组件的维护者可以在Microsoft工作。 这种情况为使用Swagger创造了先决条件，而Swagger是动态开发的，并且在最新的第三版中，在灵活性和功能方面实际上赶上了RAML。
如果不是一个而是...
事实证明，并非所有开源实用程序都已更新为OAS 3.0版本。 对于Go上的微服务而言，最关键的是缺乏使
go-swagger适应最新版本的标准。 但是，Swagger 2和Swagger 3之间的差异
很大 。 例如，在第三个版本中，开发人员：
- 认证方案的改进描述
- 完全支持JSON模式
- 增强了添加示例的能力
情况很有趣：选择标准时，您需要考虑将RAML，Swagger 2和Swagger 3作为单独的替代方案。 但是，只有Swagger 2对OpenSource工具包具有良好的支持。 RAML非常灵活……复杂，并且Swagger 3社区提供的支持很差，因此您必须使用专有工具或商业解决方案，这些工具通常非常昂贵。
同时，如果Swagger中有许多不错的功能，例如现成的门户网站
编辑器.swagger.io ，您可以在其上下载注释并通过详细的描述，链接和链接进行可视化显示，那么就不可能有更基本，更不友好的RAML。 是的，您可以在GitHub的项目中搜索某些东西，在其中找到一个类似物，然后自己进行部署。 但是，在任何情况下，都必须有人来支持门户，这对于基本使用或测试需求而言并不方便。 此外，swagger更为“无原则”，很好或更自由-它可以从代码中的注释生成，当然，这首先违背了API的原理，并且不受任何RAML实用程序的支持，
有一次，我们开始使用RAML作为一种更灵活的语言，结果，我们不得不自己动手做很多事情。 例如，一个项目在单元测试中使用了
ramlfications实用程序，该实用程序仅支持RAML 0.8。 因此，我不得不添加拐杖，以便该实用程序可以“吃掉” RAML 1.0版。
我需要选择吗？
参与为RAML添加解决方案生态系统后，我们得出的结论是，我们需要将RAML转换为Swagger 2，并且已经在其中执行了所有自动化，验证，测试和后续优化。 这是同时利用RAML的灵活性和Swagger提供的社区工具支持的好方法。
为了解决此问题，有两个OpenSource工具应确保合同的转换：
- oas-raml-converter现在是不受支持的实用程序。 在与她合作的过程中，我们发现她在复杂RAML上存在许多问题，这些RAML被“散布”在大量文件中。 该程序使用JavaScript编写，并执行语法树的递归遍历。 由于是动态类型，因此很难理解此代码，因此我们决定不浪费时间为垂死的实用程序编写补丁。
- webapi-parser是同一家公司的工具，声称可以随时随地转换所有内容。 迄今为止，已经宣布支持RAML 0.8，RAML 1.0和Swagger 2.0。 但是，在我们进行研究时，该实用程序极其粗糙且无法使用。 开发人员可以创建一种IR ，从而使他们能够在将来快速添加新标准。 但是目前，这一切都不起作用。
这还不是我们遇到的所有困难。 我们管道中的步骤之一是验证存储库中的RAML相对于规范而言是正确的。 我们尝试了几种实用程序。 令人惊讶的是，他们都在不同的地方用完全不同的坏话诅咒我们的注释。 并非总是如此：)。
最后，我们选择了一个已经过时的项目，该项目也存在许多问题（有时它突然出现，在使用正则表达式时会出现问题）。 因此，我们没有找到基于免费工具解决验证和转换任务的方法，而是决定使用商业实用程序。 将来，随着OpenSource工具的发展，解决此问题可能会变得更加容易。 同时，在我们看来，“完成”所涉及的时间和劳力比商业服务的成本更为重要。
结论
所有这些之后，我们想分享我们的经验，并请注意，在选择一种描述合同的工具之前，您需要明确确定要从中获得什么以及准备投资什么预算。 如果您忘记了OpenSource，现在有大量服务和产品可帮助您检查，转换和验证。 但是它们很昂贵，有时非常昂贵。 对于一家大公司来说，这样的成本是可以忍受的，但是对于一家初创公司而言，这可能会成为一个沉重的负担。
定义一组工具，稍后将使用。 例如，如果您只需要显示合同，则使用具有精美API的Swagger 2会更容易，因为在RAML中，您必须自己提升和维护服务。
您拥有的任务越多，对工具的需求就越广泛，并且针对不同的平台它们的作用也将有所不同，因此最好立即熟悉可用的版本以做出选择，以使将来的成本降至最低。
但是值得认识的是，当今存在的所有生态系统都是不完善的。 因此，如果公司有喜欢在RAML工作的粉丝，是因为“它可以让您更灵活地表达您的想法”，或者相反，您更喜欢Swagger，因为“它更容易理解”，所以最好让他们按照自己的方式工作。他们习惯于并希望这样做，因为任何格式的工具箱都需要使用文件来最终确定。
根据我们的经验，在以下文章中，我们将讨论我们基于RAML-Swagger架构执行哪种静态和动态检查，以及我们从合同中生成哪些文档，以及它们如何工作。