Get best of the week

指定它。Yandex报告

良好的API规范可帮助客户使用它。几个月前，在Big Pytup，Yandex开发人员Alexander BryazginBryazginnn作为OpenAPI + Swagger的示例，介绍了REST API规范的基础以及为什么需要这样的捆绑软件。从概要中，您可以了解到我们如何在现成的服务中弄乱了规范的自动生成，哪些库对我们有用，以及围绕OpenAPI规范进行了哪些调整。


大家好，我叫亚历山大。我想和您谈谈规格。



具体来说，我想谈谈几个主题。首先，以REST API规范示例为例。进一步-我们在服务中加快了规范的生成。最后，从好的方面来说，使用诸如OpenAPI和Swagger UI这样的规范示例，可以使用哪些工具进行调整以使用规范生成的结果。

REST API规范


什么是规格，在报告中这是什么意思？



首先，它是接口描述语言，它是一种描述接口的语言，是与特定格式相对应的一些描述。它可以自动分析，因为它具有严格的格式，并且其特殊性使其不依赖于实现接口的语言本身。也就是说，假设您有一个Python Web服务器，对于接口描述语言而言，这无关紧要。

有很多用于指定规格的语言。这些是REST，RPC，GraphQL等的规范。今天，我们将介绍REST规范。

Openapi


让我们使用OpenAPI示例来讨论规范。



首先，让我们了解什么是OpenAPI。这只是描述规范的语言。就其本身而言，它是一个文件-以YAML，JSON或XML格式（更喜欢它的人）-带有接口说明，句柄和方案。

昂首阔步


当我们谈论OpenAPI时，我们不能谈论Swagger。



Swagger本质上是一个OpenAPI UI，可让您漂亮地查看规范。



在Swagger中，就像在OpenAPI中一样，在规范中有对端点的描述。



您的API中有授权说明。



这里有您在API中使用的模型或电路的描述-例如，接受它作为输入或将其返回作为输出。



这里有示例说明以及您的API预期的请求和响应。



另外，在您的Swagger中，由于它是一个UI并且正在浏览器中运行，因此您可以在此处和现在实时执行对API的请求。


幻灯片链接

有了这些，您就可以在Swagger团队准备的测试台上玩耍。这是petstore.swagger.io。 Swagger提出了一个示例规范。您可以转到真正的后端并触摸。推荐。



因此，我们说：OpenAPI，Swagger，规范。但是，为什么写一个后端的人需要所有这些呢？

首先，在API的设计阶段经常使用规格。也就是说，普通人已经完成了编写后端的任务，首先要描述他们想要实现的目标。也就是说，他们开始设计API，要实现的端点列表，要使用的方案列表，参数等。在这种情况下，规范和围绕规范的工具非常方便。

此外，还有一个流行的案例。为了我们将规范拖到服务中去？这是文档。规范的可用性为您提供了一个很好的机会来描述您的API并与某人共享此信息：与您团队中的前端供应商，或与想要与您集成的外部客户。

另外，由于规范是以某种严格的格式编写的，因此可以自动处理它，即对API进行自省。最重要的是，您可以使用许多工具来简化生活。稍后，我将更详细地告诉您。

我们如何准备OpenAPI


我们决定了为什么需要所有这些。让我们谈谈我们如何在服务中加紧规范的生成。首先，有一点背景。



当我们得出要削减规格的结论时，从最初带有规格的意义上说，我们在编写项目时并没有遵循正常的方法。我们已经筹集了一些后端，它已经随我们一起飞行，并且我们希望共享规范作为一种记录方式。

而我们的后端突然使用Python。我们使用Falcon作为框架，使用棉花糖作为序列化和反序列化工具，并使用webargs作为验证工具。



使用我前面提到的来自petstore的最简单剪辑，我们将想象我们的服务在我们想要生成规范时的状态。

在我们的服务中，将有一对简化的方案：我们的宠物的类型，即类别，实际上是动物本身。



也就是说，我们将描述关于棉花糖的几种方案。此外，我们将准备一些笔以便例如注册和接收我们的收藏夹。



而且，实际上，他们将描述应用程序本身，这将引发创建和接收宠物的端点。



这就是它看起来的样子。相当简单的服务。

让我们考虑一下创建OpenAPI配置的选项。正如我前面所说，最简单，最幼稚的选项只是一个文件。我们为什么不用手制作这个文件？我们知道我们拥有什么输入数据，我们有端点。看起来很明显，只要拿起并写。



但是首先，我们是程序员。我们不喜欢用手做任何事情。我们希望为我们生成一些标准。其次，如果我们手工支持所有内容，那么我们肯定必须支持API更改以及位于其他位置的文件。像任何服务一样，我们的产品也是易变的，规格也是如此。

因此，我们得出的结论是，我们想生成一个OpenAPI配置。给定我们的技术堆栈，我们找到了一个类似apispec的库。 Apispec是制造商提供的库，即棉花糖和Webargs的作者。它们共同构成了一个庞大的生态系统。

让我们看看如何在堆栈上使用apispec来教它如何为我们生成规范。



我们有一个资源和该资源的get方法的特定处理程序。他有某种身体。



为了教apispec，让他知道我们在用笔做什么，我们在docstring中添加了一些内容。我们在那里添加了人类可以理解的描述。在我们的案例中，这是一个答案示例：有时会发生这种情况，我们的笔答案为200，而答案的主体中是带有模式Pet数据模型的JSON。





使用后请求的示例，我们描述：除了存在一个响应201（其中我们返回Pet）这一事实之外，还存在请求的预期主体。在此请求中，我们需要JSON，并且希望此JSON将采用Pet格式。



我们添加了文档字符串，然后我们需要学习如何生成规范。为此，我们编写了某种脚本，一个红色按钮，并教apispec为我们生成规范。我们声明一个apispec对象，从中我们描述服务的一些元数据，然后仅以YAML格式写入文件（生成的规范）。

让我们看看在此文件中为这个庞大的应用程序生成了什么。



首先，在此文件中，将对生成规范的版本进行描述。这一点很重要，这样，每个解释此规范的人都可以理解要解释的格式。规格因版本而异。

此外，还有我们服务的描述。这个标题，版本，如果需要的话，可能会有一些描述，然后是您可以访问的服务器列表，拉笔，查看并触摸我们的后端。



此外，我们在那里处理新芽的数据方案本身，带有类型的描述，并举例说明了该数据和一些规则。也许这些是一些极限值，也许是绑定参数。在这里，您会看到所需属性的列表。



除方案外，端点本身的描述也在那里增加。在这种情况下，对每种方法的描述就萌芽了。



使用get方法，我们获得了对get方法的描述。



恰恰是我们在相应端点的文档字符串中放入的描述发芽在帖子上。也就是说，我们已经收到某种文件。

现在我们该怎么办？有什么用？首先，作为后端的所有者，您已经可以给所有潜在的客户（使用该笔）给出此说明。这将有助于他们进行整合。也就是说，我们生成的文件不会使您眼花go乱。这是很可读的。可以通过眼睛看到它并进行某种解析。

但这也是困难的。让我们看看还有哪些其他工具可以简化您的生活，以及围绕生成的规范进行什么样的调整。

包子


然后，我们进入下一阶段，在此阶段，我们将使用OpenAPI示例讨论有关规范的有用工具箱。


幻灯片中

的链接我想谈的第一个工具是Swagger-UI。在下文中，我将提供指向您可以在其中戳出相应工具（在本例中为SwaggerHub）的Web资源或到使用Docker启动相应文档的命令的链接。

我们都非常喜欢Docker。 Docker帮助您不要在本地放置JavaScript或任何Java。只需接受它，用一个命令运行它，一切就对您有用。

因此，实际上，Swagger-UI是一个实用程序，可让您漂亮地显示您的规范。就像我之前说的那样，这些正在使用Docker（可能是Swagger）在本地运行。

您可以通过在硬件上的Swagger中运行规范来查看或共享语言环境。并进一步将您的所有潜在用户发送到此规范。她已经更加可以理解，美丽了。直接在其中可以执行查询。


幻灯片链接

除了Swagger-UI外，还有一个方便的Swagger编辑器工具。您可以在网络上使用它，也可以在本地或任何打字机上使用它。它允许您实时更改规格并在此处查看其显示。就是说，这在设计API的阶段是一个非常方便的工具，当您没有生成规范时，您想要以某种方式恶作剧或描述您的后端，而没有背后的真实或生成的后端。



接下来是很棒的Prism工具。我想更详细地介绍它。 Prism是Spotlight的实用程序。它允许您根据规范来提升模拟服务器，它将根据您喂给他的规范来工作。

也就是说，在这种情况下，我们可以看到在规范之上发布了Prism，我只是从Swagger商店下偷了它。我们看到Prism找到了规范中指定的所有端点，并说诚实地打扰了它们。

让我们尝试感受Prism可以做什么。



首先，我们找到笔，尝试拉动它，突然我们发现Prism告诉我们：对不起，401错误。我们进入规范，发现实际上这支笔隐藏在授权的后面。此处明确描述了安全性部分。在其中，我们看到授权方法是OAuth，并且我们了解：实际上，Prism期望我们提供某种授权数据。



让我们尝试根据他等待的格式将授权数据传输给他。显然，令牌是不固定的，对于Prism来说，本质上无关紧要。格式对他很重要。也就是说，如果他正在等待OAuth，则他正在等待特定格式的授权数据。

我们很讨厌授权，已经看到第400个错误。我们来看一下规范中的内容。在规范中，我们看到我们没有传递一些必需的属性。让我们继续。



魔术属性是状态。实际上，它是根据ENUM规范给出的。如果我们转移的状态未包含在此ENUM中，则将得到一个四点。

在这里，我们传递了有效状态，我们看到后端以一个完全有效的xml响应了数据。现在，仅从规范中指定的示例返回此xml中的数据。也就是说，在每个字段的规范中都有这样的部分作为示例，您可以在其中指定可以返回的数据的示例。棱镜在这里刚把他们带回来。



但是，除了您可以拔出笔头并期望会有一个诚实的两百个事实之外，还有一个机会说Prism-还给我一个特定的响应代码。通常，在规范中，我们描述了笔的不同行为，使用有效数据，它们并不总是对应于200。他们可以查看例如数据库中是否存在ID，以查看此类ID不存在。

对于这种情况，我们根据需要向任何人声明某个代码，例如第400或422。也就是说，对于有效的条目，并不总是存在有效的退出。因此，在规范中，我们描述了各种答案选项。而且，当我们抽出笔棱镜时，我们可以清楚地说：这一次我正等着您回答我，例如404错误。假设是这种情况，当我拉一个带有ID的手柄时，却没有这样的ID。



总而言之，除了我已经提到的功能以外，还有哪些一般功能？同样，这是您可以选择的模拟服务器。他将根据规范进行响应，验证授权请求。它还将验证您发送给它的数据。

除了验证请求之外，它还会生成响应。正如我所说，在最简单的情况下，它会以示例的方式生成答案。还有第二种选择-当您明确要求时：请生成动态答案。动态策略意味着根据类型（例如int），它会生成数千，数十亿美元或其他内容。或对于字符串，一个奇怪且难以理解的哈希。

另外，当我在第一次运行时说可以生成数据时，我们问自己：如果Prism与伪造者集成在一起，那将很酷。那些使用Python造假者的人可能知道，当您想锁定数据库中的某些数据或模拟数据时，它有多酷。

因此，Prism是用JavaScript编写的。 JavaScript还具有Faker.js，Prism具有与造假者的自动集成。您可以在规范中明确指定笔将提供的伪造数据的类型。也就是说，OpenAPI支持一个插件系统，该系统允许您扩展规范，以便OpenAPI和解析器本身不关心。但是，如果有解析您规范的插件，则它们可以使用其他一些字段。

因此，Prism提供您使用可选的X-faker插件字段。非常舒适。

在此，我用星号表示可以在OpenAPI中描述回调。这是一种交互方案，当您注册某个笔的回调并等待之后，您将收到针对您注册的URL的特定回调。因此，Prism知道如何弄湿。

有趣的是：棱镜不仅可以在模拟模式下提高，而且可以在代理模式下提高。您只需将此Proxy放在您的真实后端之前，所有通过Prism并返回的请求，Prism都会按照规范进行验证。

如果某些数据（例如输入或输出，请求或响应）将发生分歧，则他会将其写入日志中。他非常透明地执行此操作，不会影响实际行为。通常，该文档说可以在生产中轻松提高它。老实说，我自己还没有尝试过。当然会有一些开销，但是我仍然不能说。您可以感觉到，尝试说出来。

此外，通过我已经说过的，可以强制执行某些请求。也就是说，来到模拟服务器并说：我想要一个特定的示例或响应类型。我们已经讨论过答案的类型。同样在OpenAPI规范中，可以指定几个答案选项并显式命名它们。

因此，您可以说Prism：这一次，我想举一个具体的例子，下一次，我想举另一个例子。


幻灯片链接

关于棱镜谈到。现在关于邮递员。我很爱他。因此，Postman具有与OpenAPI的现成集成。您只需单击两下即可从字面上导入OpenAPI规范。并且他将根据您的规范创建一个请求集合。

同时，他将预先准备所有查询参数，所有正文参数，所有环境和授权。您只需要使用一些真实的ID或其他东西（授权令牌）来完成数据。非常舒适。



我们从邮递员那里进一步经过。我们谈论过Prism，它具有功能-查询验证。实际上，有一个单独的实用程序，可让您毫不留情地吮吸您真正运行的后端，并查看它是否真正符合规范。

Dredd解析规范。他拿起，拉起所有的笔，看一看还给他的东西。通常，可以将dredd视为编写测试的基础结构，因为可以用其钩子来补充其所有请求。也就是说，您可以从盒子中按原样启动dredd，就像我在这里启动它一样。

或者，您可以通过向drdd传递一组在常规测试的意识形态中实际起作用的钩子来运行drdd。整个测试集都有其发展之处，在测试之前，测试之后以及整个基础架构中都运行着钩子。


幻灯片中的链接

接下来，我想更详细地讨论Swagger本身提供的Swagger-codegen这样的工具。实际上，它有点像瑞士刀。首先，这些人在编写此乐器时有什么样的想法。

通常，当某人需要与后端集成时，您很少会在某个阶段的业务逻辑中在此处描述http请求。大多数情况下，您会在客户端的某些实体中封装具有特定后端的工作。

因此，伙计们想到了一个想法，即有了一个规范，我们就可以很清楚地描述和预测该后端客户端的外观。这些家伙创造了一个客户生成器。



让我们尝试根据petstore规范开始生成客户端。我们将看到此生成器是由Swagger客户端本身生成的，其中包含Python客户端本身。在启动行中，您可以清楚地看到我正在用Python生成客户端。实际上，它支持多种语言。这里重要的是什么？领先者会喜欢JavaScript，赶时髦的人会喜欢Go。所有你想要的。

因此，除了Python的客户端外，他还生成了一些文档和测试Magic文件夹。稍后我们将更详细地讨论它们。还有很多糖，以便您可以将此客户端包装在现成的库中。有gitignore，有CI文件，对于Travis说，有git的糖。有需求setup.py和tox.ini。就是说，所有可以帮助您简单地获取，提交和发送该客户端的东西都已经以可重用的库的形式存在。

让我们仔细看看他在客户端中生成的内容。



在客户端中，除了生成一些辅助文件之外，他还生成了两个非常重要的目录api和模型。在模型中，我们拥有要操纵的数据模型。每个模型都只是一个从__init__从对象继承的Python类，该类接受此方案的各种参数，以及用于更改对象状态的getter和setter。



除了模型之外，诸如PetApi之类的实体也在那里出现-这些只是端点组上的客户端包装，OpenAPI按标签或端点进行分组。

该客户端拥有您可以抽动的所有笔，可以传输实际数据。然后他们将飞向某个后端。



这个生成的客户端实现了什么？从有趣的-合同方式。让我们更多地谈论他。

合同的编程方法建议，当您实现客户端与服务器之间的交互时，实际上您总是会遵循某些规则，合同，无论是客户端提供给服务器的数据还是服务器提供给客户端的数据。

因此，合同方法建议您每次都实时检查数据和交互是否符合合同要求。如果此合同是我们传输的数据方案，并且不满足我们的期望，不满意，那么您需要这样说，并在此时此刻显示错误。不要去真正的后端，不要等待任何四个点，而是现在就说。

还是另一种情况：我们去了后端，收到了一些数据，但是它们与我们等待的数据不符。假设我们希望看到的某些字段为空。我们现在就在这里谈论它，而不是当我们在森林中某个地方的调用堆栈中某个地方闲逛，并且不知道为什么某些东西掉了下来的时候。

因此，Swagger-codegen根据合同方法生成客户端和模型。它允许您实时地说：是的，我希望客户端在运行时检查所有数据是否符合合同要求。如果合同不满意，他会立即说。



我们通过合同方式生成了一些pit-client，但是除此之外，Swagger-codegen还为我们生成了文档存根。实际上，它们非常简单，但是对于每种模型，它们都可以被扭曲。



Swagger-codegen也生成了某种测试存根。一切都是为了使您能够以最小的努力推出生成的代码，并通过Continuous Integration进行测试，并以带有git的库的形式，通过所有杂项来运行它。



让我们再次简要地介绍一下。我们仅考察了一种情况-一种为API生成客户端的方法。从重要的}合同方法。我想说：当我根据他们的规范为一个真正的petstore生成一个客户端并真正转到他们的后端时，突然之间，这种合同方法捕获了petstore返回的无效数据。

起初我以为-他们有点奇怪。它们本身生成了规范，后端对于它们而言无法正常工作。但是在我看来，他们是故意这样做的，以便我们可以看到合同方法的威力。没有太多数据，并且清楚地生成了它们。

同样在客户群和下一代中，您可以使用自己的模板。也就是说，如果您希望以某种格式生成客户端，则可以保存并准备模板并以所需方式生成客户端。如果您每天走动并生成集成，您可能会非常喜欢。

您还可以配置这些客户端并编写模型的导入，而不是由Swagger-codegen生成的模型。

除了为API生成客户端之外，您还可以将规范提供给生成器并生成服务器本身的存根。这很奇怪。也就是说，您生成了某种可以按照规范工作的后端。显然，那里没有业务逻辑。但是，作为某种脚手架，也可能会很方便，即准备草稿，您已经可以使用该草稿。我没有使用过，但是我建议您看一下-也许您会发现一些对自己有用的东西。

除其他事项外，如果有人使用它，它还可以生成HTML和Confluence格式的文档。我想为OpenAPI展示的示例也就此结束。


幻灯片下面的两个链接中提供了所有这些工具：openapi.tools和github.com/APIs-guru/awesome-openapi3

我想展示围绕OpenAPI规范的调整组。实际上，有很多工具。这些只是组，即可以使用的工具类型。

在此重要的是从一种规范到另一种规范的转换器。也就是说，您可以从OpenAPI规范中生成Blueprint API或任何您喜欢的东西，反之亦然。有一个用于模拟的库，用于文档。也就是说，我所谈论的一切都会反映在这些小组中。

您也可以跟随一个链接。一定要去看看。


幻灯片链接

除了围绕OpenAPI的工具之外，还有关于Swagger的工具。有SwaggerHub和Swagger检查器。它们是蓝色的，因为它是一个基于Web的工具包，因此以蓝色突出显示。您可以直接转到那里，并使用SwaggerHub和Swagger Inspector作为服务，它们实际上是以下库的叠加：Swagger-editor，Swagger-codegen，Swagger-UI。我们刚才讨论的所有内容。

所有库都是黄色的；正如我们所见，它们是开源的。在GitHub上以Docker的形式存在。采用。

结论




今天我们讨论了什么？以OpenAPI和Swagger为例的REST API规范。我想强调一下，OpenAPI只是描述规范的一种方法。很多。在有趣的组件中，另请参阅Blueprint API。也许别人会喜欢的。



我们还观看了Swagger。从本质上讲，正如我们已经说过的，这只是围绕规范的漂亮UI，它使您可以方便地查看和探索它。实际上，这些工具也很多，从流行的ReDoc和Sphinx到实际上的Markdown，不一而足。也就是说，您可以从OpenAPI生成Markdown，并且可以在所有GitHub，GitLab（无论您想要在哪里）中完美地显示它。

我们还查看了技术堆栈上的示例，现在我们如何生成规范。但是，正如您注意到的那样，这非常复杂且不便，因为实际上，我们重复了业务逻辑和文档字符串。


幻灯片中的链接：FastAPI，SAFRS，rororo

有趣的是，我建议您看一下FastAPI。Styopa 今天将告诉您更多有关此的信息。 FastAPI可帮助您开箱即用地生成规范。您在那里根本什么都想不到。只需编写代码并获得完成的规格即可。

还有两个框架：SAFRS和rororo。这些名字当然是神奇的。他们在不同的模型上工作了一点，不要让您不去考虑规范，而只是把它当作副作用。相反，您有一个驱动处理程序的规范。大致来说，这是规范驱动的开发。它们没有FastAPI那么多星，但在我看来，它们值得关注，请看一看。



最后，我们使用OpenAPI和Swagger的示例讨论了规范周围存在哪种实用程序。对于我提出的所有链接，请确保有很多有趣的东西：

-OpenAPI / Swagger
swagger.io/docs/specification/about-

猎鹰+棉花糖+ apispec的
示例github.com/marshmallow-code/apispec
github.com/tiangolo/fastapi-OpenAPI

/ Swagger
包子
openapi.tools swagger.io/tools swagger.io/tools/open-source/open-source-integrations github.com/APIs-guru/awesome-openapi3

我有什么是报告的信息吗？伙计们，写规范并不是某种官僚主义。这并不像乍看起来那样困难，而是简单易用，并提供了许多有用的工具，为您带来了巨大商机。

写下规格。推荐。非常感谢。


演示文稿中提供了所有代码和链接。

More articles:


All Articles