Lane:我想和你分享一下为什么API规范很重要的高层次观点。如何OpenAPI，AsyncAPI，JSON Schema等。可以帮助我们以机器理解的方式标准化和交付API生命周期。此外，它还使我们人类能够在API生命周期中更好地交流、合作和进步。 　　

　　

　　我叫金莱恩。我是邮递员的首席传教士。我领导我们的开放技术团队，该团队包括我们的DevRel、我们的API生命周期小组，我还投资于API规范，如OpenAPI、AsyncAPI和JSON Schema，以及围绕它们的工具。API规范对我和邮差来说很重要。我想分享一点我们认为API规范如何影响我们生产和使用API的方式。 　　

　　

　　 　　

　　

　　API规范不是新的API规范不是新的。在过去的20年里，WSDL一直在定义网络服务。随着更多基于网络的API方法的出现，我们也看到了WADL的发展来帮助我们描述API的表面区域。真的，直到2010年和11年Swagger的问世，才帮助我们使我们的文档更具交互性和实用性。只有帮助开发者理解API的作用和使用方法，才能真正开始看到API规范的好处。到了2015年，斯瓦格已经长大了。这是第二版。它被放入Linux基金会，OpenAPI计划被创建来促进规范的发展，并被重新命名为OpenAPI。帮我们描述一下过去五六年的HTTP API和webhook。为我们如何定义、设计、交付、部署和丢弃API提供一个基础。 　　

　　

　　 　　

　　

　　OpenAPI我们来看看Open API。OpenAPI允许我们描述同步API的表面积，描述信息，API的功能，在哪里可以找到它，服务器。更重要的是，每个响应的路径、参数和细节，包括被解析为请求体或作为每个响应的一部分返回的模式。OpenAPI为我们提供了一种机器可读的JSON或YAML方式来描述我们的API是什么以及HTTP/1.1 API做什么，并允许开发人员在API生命周期的不同点使用该规范。 　　

　　

　　异步API 　　

　　

　　AsyncAPI允许我们描述基于OpenAPI的异步API的外围应用，但允许我们描述通道、消息和绑定。跨TCP、MQTT和AMQP执行发布和订阅API。我们允许定义这些API如何跨多个协议工作，并定义哪些模式被用作发布和订阅的有效负载的一部分，哪些消息被来回发送到这些异步API。OpenAPI和AsyncAPI都允许我们在今天的工具箱中描述大多数API。 　　

　　

　　 　　

　　

　　JSON模式允许我们描述和验证这些API的有效负载。为我们提供了一种机器可读的方式来描述对象、它们的属性、它们包含的数据类型以及实际需要什么，以便我们可以验证这些对象。Schema用于多个OpenAPI和AsyncAPI。它们有自己的JSON模式词汇表，这允许它们在OpenAPI的情况下描述和验证请求和响应有效负载。在AsyncAPI上下文中发布和订阅有效负载。提供一种机器可读的方式，允许我们描述我们的API在做什么。哪些资源被来回解析，然后哪些功能被封装在这些非常抽象的API中，通常很难查看和验证。 　　

　　

　　API规范为API生命周期提供动力。API规范用于支持API生命周期中的多个站点。最值得注意的是，它用于文档。很多用Swagger的人都觉得Swagger是个文档。实际上，Swagger是一个可以用来生成文档的规范。用Swagger、OpenAPI和AsyncAPI来描述每个API的技术细节。然后允许我们发布文档。允许我们始终保持我们的文档是最新的，并且通过使用这个API规范使用开源或商业选项生成文档，在团队之间交付一致的文档。API规范也用于生成模拟服务器。这些模拟服务器可以是API设计优先级方法的一部分。设计它并模拟它，这样你就可以确保它做它需要做的事情。它可以作为QA和测试的一部分。然后，一些团体在生产环境中将其用于沙盒，因此开发人员在学习API的作用时实际上不必处理生产数据。API也被用作测试的支架。允许API生产者生成合同、集成、性能和其他类型的测试，以帮助他们确保API正在做它应该做的事情，将这些测试作为管道的一部分运行，或者使用监视器来调度它们。 　　

> 　　

相同的方法可用于安全性。您可以使用 OpenAPI 规范或异步扫描 API 的表面区域以查找漏洞，审核身份验证。使用 OWASP Top 10 检查其他常见漏洞，尝试了解您的 API 是否安全，因为它们应该在团队之间保持一致。API 规范支持生命周期的另一种常见方式是通过代码生成。许多公司正在使用 OpenAPI 和 AsyncAPI 来生成客户端或服务器端代码，因此您实际上可以使用规范来生成代码，以便您部署 API、将其部署到网关或生成各种编程语言的 SDK。允许公司生产 SDK，各种编程语言的库和代码片段，而无需在团队中具备这些编程语言技能。这真的是一个重要的看为什么规格很重要。它不仅适用于文档，还适用于整个生命周期。API 的一个规范可用于生成文档、模拟、测试、保护该 API，然后生成您将使用的代码来实际将该 API 变为现实或将其用于集成或应用程序中。

　　

将 API 规范变为现实的多种方法您可以通过多种方式将 API 规范变为现实。最值得注意和最近的方法之一是通过设计优先的方法。你从一个 OpenAPI 或 AsyncAPI 开始，生成一个模板，然后手工设计它，确保它完全符合你的需要。然后生成一个模拟服务器并发布文档，以便其他利益相关者、其他团队成员可以使用它并就该 API 提供反馈，允许您在实际编写代码之前设计 API、模拟它并记录它。然后，一旦您对它进行了足够的迭代，您就可以将其作为 API 发布。

　　

生成 API 规范的第二种常见方式是代码优先。团队开始编写代码，做他们最擅长的事情。然后，在编写代码时，您可以对其进行注释，或者使用网关或代理。您可以从代码生成 OpenAPI 和 AsyncAPI。你先编码。您生成 OpenAPI 或 AsyncAPI，然后可用于生成文档测试并帮助保护您的 API。另一种常见的方法是对 Web 或移动应用程序进行逆向工程，并为已在生产中、已在应用程序中使用的 API 生成 OpenAPI 或 AsyncAPI。然后，只需要发布文档并保持最新。生成测试并保护该 API，允许将现有 API 引入更标准化的 API 生命周期，并与其他设计或代码优先的 API 一起使用。

　　

行业标准使用规范

　　

API 规范在行业标准中发挥着关键作用，尤其是 PSD2。您可以在欧盟之外找到适用于 PSD2 标准的 OpenAPI，该标准用于管理和规范金融和支付 API 的部署和发展方式。您可以看到 OpenAPI 被用于火灾规范，定义了 API 在医疗保健领域的交付方式。提供每个请求和响应的所有技术细节，帮助提高医疗保健的互操作性。Open Referral 是另一个 API 标准，它使用 OpenAPI 为市政、市级、县级卫生和公共服务提供定义，使城市可以更轻松地跨州和跨国家共享数据。另一个是 OpenTravel，它塑造了我们在旅游业中交付 API 的方式，与航空公司合作，招待活动和其他事情。提供可用于部署旅行 API 的通用标准集，使行业更具互操作性。另一个例子是地理空间联盟。他们正在制定地理 API 标准，您可以找到他们 API 的 OpenAPI 规范。这只是一个快照。还有很多其他标准，包括汽车行业和保险。在 API 产生影响的大多数行业中，您都可以找到 OpenAPI，并且越来越多地使用 AsyncAPI 来定义该领域。s 许多其他标准，包括汽车行业和保险。在 API 产生影响的大多数行业中，您都可以找到 OpenAPI，并且越来越多地使用 AsyncAPI 来定义该领域。s 许多其他标准，包括汽车行业和保险。在 API 产生影响的大多数行业中，您都可以找到 OpenAPI，并且越来越多地使用 AsyncAPI 来定义该领域。

　　

　　

规范提供治理框架OpenAPI、AsyncAPI 和 JSON Schema 到位后，为我们提供了实现跨大型企业组织治理的框架。OpenAPI 和 AsyncAPI 为我们提供了设置设计指南的能力。应该如何描述我们的路径？什么参数？他们应该是骆驼案还是蛇案？架构应该是什么样的？模式如何演变以最小化破坏性更改？所有这些设计指南都可以以机器可读的方式编码并应用于 OpenAPI 和 AsyncAPI。整理规则。lint 描述 API 的 OpenAPI 或 AsyncAPI 是很常见的，因此您可以验证它是否具有特定的结构和形式。这就是 linting 为我们提供的。我们可以定义构成我们的设计指南和整体企业治理的规则。我们可以将这些规则应用于我们的 API 合约 已定义。然后我们可以使用合同测试来应用它，这样我们就可以验证这些规则是否在设计时、开发时以及构建时得到应用。

　　

这些规范使我们能够掌握变更管理。这些对象由模式定义。这些由 OpenAPI 和 AsyncAPI 定义的提供对这些对象的访问的 API 将随着时间而改变。OpenAPI、AsyncAPI 和 JSON Schema 允许我们量化这种变化。对此应用基于语义日期或其他类型的版本控制，并掌握这些资源和功能如何发展。然后我们可以自动化所有这些。在编辑 OpenAPI、Async 或 JSON Schema 时，我们可以将其自动化，以便在设计工具中获得实时反馈。您可以在 IDE 或命令行中的管道或开发时应用，并允许在整个 API 生命周期和跨开发团队中实现治理，帮助他们自动化应用治理的方式。然后一路学习，

　　

API 规范是我们作为一个团队一起工作的方式，因此您可以在文档中看到这些证据。为什么 Swagger UI 和 Redoc 以及规范驱动的文档变得如此重要。这就是我们 API 生产者与 API 消费者沟通的方式。这些规范随着它们的发展和在整个 API 生命周期中的应用，为协作开辟了机会。我们现在可以共享工件。当我说 API 分页时，我可以分享我的意思。这是它的规范。当我说这是一个图像对象时，我可以分享我的意思。我可以为此分享 JSON Schema。围绕这些工件的共享和协作使我们能够更紧密地合作，并在这些结构中具有相同的含义。然后因为我们可以使用现有的源代码控制来烘焙它，所以我们拥有这些工件。

　　

我们的 OpenAPI 和 AsyncAPI 位于设计它们的工作区中。它们存在于 GitHub、GitLab 和 Bitbucket 存储库中，代码在这些存储库中被提交，并被跨基础设施使用，以使用这些 API 进行部署和自动化。所有这一切使我们能够跨团队进行标准化，因此我们可以更好地沟通、协作、共享，并且我们拥有这些工件，可以帮助我们理解谈论这些非常抽象的 API 概念时的含义。它可以帮助我们达成一致，标准化我们做事的方式，然后通过源代码控制实现自动化。这可以在团队级别、组织级别完成，也可以在行业级别使用标准，使 API 在其整个生命周期中更加一致和迭代。

　　

规范是我们业务运营的语言当这些 OpenAPI 成熟时，它们为我们提供了定义我们操作的不同领域的能力。这就是我们如何区分不同的业务线、我们用来运营的不同领域的方式。它可以很好地描述和定义我们的团队是如何组成的。我们如何组织我们的团队，以及他们如何在这些不同的业务线和团队中工作。OpenAPI、AsyncAPI 和 JSON Schema 以及它们之间的标记，使我们能够在这些不同的领域中划分我们所有的资源和数字能力，描述我们拥有的不同资源。不同的图像、视频、人物和地址，我们拥有的所有不同的数字资源，以及跨这些资源采取的能力、算法和行动。在 OpenAPI 中描述所有这些，标记事物，帮助我们建立和形式化我们描述它的词汇。我们使用这些模式作为请求的一部分发布到 API，在事件驱动的 API 世界中作为响应返回、发布、订阅。我们正在标准化我们如何描述这些对象，我们如何谈论它们。我们正在减少这些资源和功能的冗余，为我们的运营方式创建更多的逻辑域。确保它尽可能高效且定义明确。然后领域专家可以真正帮助指导和管理我们业务运营的这一部分。重新标准化我们如何描述这些对象，我们如何谈论它们。我们正在减少这些资源和功能的冗余，为我们的运营方式创建更多的逻辑域。确保它尽可能高效且定义明确。然后领域专家可以真正帮助指导和管理我们业务运营的这一部分。重新标准化我们如何描述这些对象，我们如何谈论它们。我们正在减少这些资源和功能的冗余，为我们的运营方式创建更多的逻辑域。确保它尽可能高效且定义明确。然后领域专家可以真正帮助指导和管理我们业务运营的这一部分。

　　

规格适用于人和机器规范适用于人和机器。尽管它们是用 JSON 或 YAML 编写的，并且非常机器可读且结构化，因此它们可以导入到不同的服务和工具中。它们可以用作源代码控制的一部分。API 生命周期可以通过这种方式实现自动化。它们也非常适合人类。我们使用它们非常重要。迭代它们。记录它们，并让人们可以在他们的工作中使用它们。规范通常被视为一种开发工具。它们越来越多地被项目和工程经理、API 设计师和架构师用来塑造整个企业组织的领域，并用作进行设计审查、安全审查和其他方式的一种方式。将其用作工件来指导与实际构建 API 和在其之上的应用程序的开发人员的对话。重要的是要使规范保持最新，因为人类依赖于此。这些规范正在帮助我们解决我们在整个组织中遇到的许多人为挑战和摩擦。提升它、缩小它并将规范视为文档或代码生成或只是某个服务器上某处的 JSON 工件，这一点很重要。这在很大程度上是人类用来推进我们的运营并取得成功的合同。这些规范正在帮助我们解决我们在整个组织中遇到的许多人为挑战和摩擦。提升它、缩小它并将规范视为文档或代码生成或只是某个服务器上某处的 JSON 工件，这一点很重要。这在很大程度上是人类用来推进我们的运营并取得成功的合同。这些规范正在帮助我们解决我们在整个组织中遇到的许多人为挑战和摩擦。提升它、缩小它并将规范视为文档或代码生成或只是某个服务器上某处的 JSON 工件，这一点很重要。这在很大程度上是人类用来推进我们的运营并取得成功的合同。

　　

标准化、规范驱动的 API 生命周期标准化的 API 生命周期意味着我们将所有这些资源和功能定义为机器可读的工件。我们不仅仅关注 HTTP/1.1、REST 或现有的 API 部署方式。我们有一个多样化的工件工具箱，允许我们描述事件驱动和消息驱动、GraphQL、gRPC、Kafka、NATS。我们能够使用一整套 API 解决方案来帮助我们描述、定义、交付和操作这些 API，从而使生产者和消费者都受益。这有助于我们标准化我们定义和设计 API 的方式。我们如何交付。我们是如何在跨团队、跨组织的情况下大规模开展这项工作的。当你去一个大型企业集团，你去让一个 API 工作时，它具有相同的特性。它具有相同的属性、参数。它具有一致的文档。它有我需要的代码库，并且它们使用与我正在使用的编程语言相匹配的约定。

　　

所有这些都是由这些 API 规范驱动的。OpenAPI 和 AsyncAPI 被用作这方面的护栏。它们正在与合作伙伴和第三方消费者一起发布到组织内部或外部的中央目录。这些 OpenAPI、AsyncAPI 和 JSON Schema 可用于任何服务或工具。API 生产者拥有更流畅、高速、高效、敏捷和灵活的方式来交付 API，能够响应变化并将其 API 发布出去。这些 API 的消费者可以访问这些相同的合约，因此他们知道事情何时发生变化。他们能够围绕这些 API 自动化、构建和集成，而无需阅读文档。他们可以只导入一个 OpenAPI。他们可以导入 AsyncAPI。他们可以使用 JSON Schema 来验证和测试。然后他们可以获取 API 生产者围绕这些规范构建的所有工具，并将它们投入使用。

　　

标准化的规范驱动的 API 生命周期是您在过去十年中使用公共 API 或在过去五六年大量投资于微服务的大多数企业组织中看到的。您会看到他们确实在努力掌握在整个企业组织中使用 OpenAPI 的方法。采用和学习如何使用 AsyncAPI。然后使用 JSON Schema 来处理正在解析的内部数据、模式、工件。这是组织、架构师和一些更先进的前倾公司的领导层采用这些 API 规范的第一要务。围绕它们进行标准化。然后，在众所周知的 API 生命周期中应用它。

　　

概括我知道很多人在谈到 API 时都陷入了困境，只关注文档或代码生成，或者围绕这些 OpenAPI 进行设计和架构。希望这可以缩小并展示 OpenAPI、AsyncAPI 和 JSON Schema 是如何协同工作的。更重要的是，它们如何在一致的 API 生命周期中应用。因为一旦您可以通过这种方式在整个生命周期内对其进行标准化和稳定化，您将开始看到在运营速度、性能、质量和正在发生的事情的整体治理方面所带来的好处。我建议转到 OpenAPI、AsyncAPI 或 JSON Schema，这三种开源解决方案都可以让您描述您将如何使用 API。这些社区中的每一个都可以作为您运营的一部分，从中学习并投入工作。

　　

问题和解答Betts：规范是针对人和机器的，似乎是一个反复出现的主题。主题演讲是关于程序员的大脑以及阅读和理解代码所需的内容。稍后还有另一场谈话谈到了可读性因素，即代码需要可读。你能更深入地了解它的可读性吗？因为我看到了 YAML，而且我认为这不是人类可读的。它可能是程序员可读的。是什么使它具有人类可读性？

　　

Lane：YAML 是一个开始。当从 JSON 切换到 YAML 时，我已经看到业务利益相关者会更多地参与其中，令人惊讶的是，括号、逗号和引号的消失会起到什么作用。我同意。它仍然适用于程序员。如何使其更具可读性是使它们的范围更小。与其创建大型的单体 API，不如创建更小的微服务和更小的基于产品的 API，这些 API 更易于理解它们在范围内的作用。然后，您遵循领域驱动设计，并进行事件风暴。你真的会在语言中找到尽可能有意义和有目的的词汇。API 的设计很直观。它与域对话。它与业务对话中的利益相关者交谈。所有这些都将为此做出贡献。不是拉丁语或希腊语，当它在 YAML 中时尝试阅读它，这是我们习惯的熟悉词汇。它的范围很简单，而且对人们来说更容易消化。所有这些设计工作确实有助于实现这一点。我同意，我们还有很长的路要走，OpenAPI 或 JSON Schema 仍然比它应该的技术要多一些。

　　

Betts：工具是否到位，您可以生成更易于阅读的文档？就是这样，使用 YAML，使用 JSON Schema 来组织常用词，然后有人会阅读你的 Swagger 页面，不管它是什么。

　　

Lane：我是第一个承认，真正的 OpenAPI、AsyncAPI，它们只是我们正在寻找的任何其他结果的配置文件。真的，我们人类不应该那么在意它。我们应该能够点击查看源代码。我们应该能够访问配置文件。确实，最终结果是我们应该得到的结果。这取决于工具和服务提供商来帮助我们实现目标。在那之前，我们需要稍微提升这些规范，吸引更多的眼球，让更多的人使用它们，这样工具才能让我们到达那里。

　　

Betts：既然你提到了 DDD，我就想问这个问题，因为 DDD 有泛在语言的概念。它是有界上下文中无处不在的语言。在这里，您正在谈论您的 API，即外部接口。它仍然是一种无处不在的语言，但它处于不同的层次。有不同的人参与吗？是业务利益相关者，而不是开发团队与他们的技术产品经理一起工作吗？

　　

Lane：是的，非常多，这取决于您正在构建的 API 和服务的范围。OpenAPI，无论是更多产品、面向外部的 API，还是微服务。无论您有事件驱动的微服务，还是使用更异步的 Kafka 将它们连接在一起，这种方法，一种事件驱动的方法。您的域对话将根据您要完成的任务而形成。只是内部吗？只是私人的吗？是和合作伙伴一起吗？是行业焦点吗？您的领域将非常受这些目标和目标的限制。它因景观而异。真的，这是你应该做的领域驱动的设计练习，是充实的。我们的域名是什么？什么是有界上下文？我们的界面应该是什么样的？我们所有的对象应该是什么？重新解析？他们协同工作。仅仅基于它是内部的、合作伙伴的、私人的，你的观众是谁，真的会定义很多。

　　

Betts：这些规范讨论了请求-响应、输入以及立即返回的输出，但它并没有提供稍后发生的内容那么深入。有这方面的例子吗？当我将此请求发送到我的 API 时，是否有关于触发哪些事件的规范？因为那时您可以记录所有规范。

　　

莱恩：是的。AsyncAPI 具有事件驱动发布和订阅的概念。两者之间有一个维恩图重叠。我不会说它应该是连贯和清晰的。比如说，我正在使用一个常规的 API 来发出请求和响应，我如何了解 webhook 以便获得推送？在我提出请求后，我得到了回复，我收到了回复，但之后还会发生一些其他事情。在 OpenAPI 中，您可以说有链接对象，这就是下一步。这就是接下来的事情。我相信你甚至可以说，如果你想订阅这个，这里有一个 WebSockets 标头，它会指向一个 WebSockets 来实际订阅它。我见过几个在 HTTP 和 TCP 之间进行切换的比特币 API，即 WebSockets。至于您如何在 OpenAPI 和 AsyncAPI 中描述请求和响应以及事件驱动世界之间的关系，它并不像应有的那样顺畅。我看到很多人都在努力让它变得更有意义。

　　

Betts：其他问题之一是关于分页、扩展、国际化等公共部分的子规范？您能否在两个文件之间进行链接，以便每个人都不必重复在您的所有服务中通用的相同标志定义？

　　

莱恩：是的，重复使用。在 OpenAPI、JSON Schema 和 AsyncAPI 中，您可以引用，所以有一个美元符号 ref。OpenAPI 3 非常注重重用。它有一个组件库，您可以在其中放置参数和放置东西，然后只需在文档中引用它们。您也可以在 OpenAPI 之外执行此操作。您可以拥有一个 OpenAPI，就像您的所有公共部分、您的分页、您的请求正文以及您重用的所有东西一样。然后，您可以在 OpenAPI 中引用具有完整 URL 的那些，并重用它们。这个概念存在于所有三个规格中。问题在于对此的工具支持，因为工具支持并不像应有的那样健壮和一致。这是我们真正正在努力的事情，因为那里有很多很棒的模式，很多很棒的可重用模式我们可以投入使用。帮助你做到这一点的工具，你必须知道如何做到这一点，并且成为一个手工编辑你的 OpenAPI 的铁杆，而不是在这些日子里依赖工具来做到这一点。我们将在未来一两年内解决这个问题。

　　

Betts：在同样的轨迹上，您提到 Swagger 大约在 10 年前，但后来成为 OpenAPI，成为 Linux 基金会的一部分，2015 年。AsyncAPI 延迟了几年。它今年刚刚进入 Linux 基金会。它刚刚达到第二版。是不是同样的事情，只是退后几年？我们是否可以期待类似的情况，需要几年时间才能到达那里，还是会更快地增长？

　　

莱恩：我认为它会增长得更快。当谈到 Swagger 时，我觉得我们非常像 2012 年，比如工具的数量，它周围空间的能量。我们在 AsyncAPI 方面也处于同一点，但由于核心工具的存在，我们将更快地到达那里。OpenAPI Initiative 不管理任何工具。它仅将规范作为 Linux 基金会的一部分进行管理。当 Tony Tam 创建 Swagger 并运行 Swagger 时，他有 Swagger UI。他有 Swagger 代码生成器。他有核心工具。在 2.0 版本中，正是这种共生关系让 Swagger 得以迅速发展。我们在 3.0 中遇到了麻烦。核心工具以及解析器、生成器、文档、代码生成和规范之间的关系至关重要。这就是 AsyncAPI 会爆炸的原因。已经爆了

　　

Betts：这类似于你的 API 开始被使用，你必须担心向后兼容性。你必须让更多的人开心并做出更多的决定，并且随着你的发展可能会慢一点，这样你就可以实现下一个伟大的事情。

　　

莱恩：你必须更周到。

　　

Betts：所有这些资源都可以创建这个非常多样化的工具箱。您提到了 REST、gRPC 和 GraphQL。这些工具适用于所有技术堆栈，但它们是否成熟，或者 REST、JSON 比 gRPC 和 GraphQL 更进一步？

　　

莱恩：我们正在达到成熟点。GraphQL 和 gRPC 在企业工具箱中都非常成熟，被广泛采用。社区范围没有那么大，从讲故事的角度来看，你在空间中听到的内容并不完全有信心。在那里。在那里，毫无疑问，我看到很多涉及这两者的企业采用。我看到了整个光谱。我将带有 GraphQL 的 WebSockets 视为发布和订阅，这是一个有趣的混合体。然后使用 gRPC，我看到在 JSON Schema 和其他东西的序列化方面有很多二进制投资。它们正在达到成熟点，并且开始影响范围的其余部分，但 REST 有一个巨大的领先优势。